Errors

{
  "error": {
    "name": "unprocessableEntity",
    "status": "422",
    "type": "requestError",
    "description": "There was a problem with the request.",
    "details": {
      "code": "validationError",
      "detailCode": "",
      "description": "There are requirements that have not been met.",
      "parameter": "amount",
      "explanation": "amount is required"
    },
    "ref": "5540b94cffee444cb4e12b761ca93183"
  }
}

The Error response structure contains a HTTP status code, an error type, an error code, a reference id, and (optionally) other details to further understand the nature of the error. The Error response has a root element "error" containing the error structure.

Parameter

Description

error

Errors come wrapped in a root object named "error". See below.

Error

Parameter

Description

name

The HTTP status code name. See below for more information.

status

The HTTP status code. See below for more information.

type

The error type. See below for more information.

description

The description for the error type.

details

An embedded details object. See below for more information.

ref

A unique reference code given to each error.

Details

Parameter

Description

code

The error detail code. See below for more information.

description

The description for the error detail code.

detailCode

A code given to describe the specific details of the error.

parameter

The parameter associated with the error (if available).

value

The parameter values associated with the error (if available).

explanation

A more detailed explanation of the error (if available).

HTTP status codes

The Error response uses HTTP Status Codes 2xx, 4xx, and 5xx.

When the request cannot be understood, due to a possibly malformed request, HTTP Status Code 400 is usually returned.

When the request is well-formed but contains validation errors, HTTP Status Code 422 is usually returned.

When a request passes validation but otherwise fails for other reasons (card declined for example), HTTP Status Code 402 is usually returned.

Status Code

Status Name

Description

200

Success

The request was successful.

204

No Content

Empty response.

400

Bad Request

The request failed, possibly due to a malformed request.

401

Unauthorized

Access to the resource is denied

402

Request Failed

The request was not successful despite being a valid request.

404

Not Found

The resource was not found

422

Unprocessable Entity

The request failed, possibly due to validation problems.

429

Too Many Requests

You have performed too many requests

500

Internal Server Error

Something went wrong on the Paystand end.

503

Service Unavailable

The API is currently not available.

Detail codes

Error Detail Codes give a more granular description of an error.

There are access errors, validation errors, resource failure errors, and more general errors.

Detail Code

Description

apiError

The request failed due to an API error

insufficientResourceAccess

You do not have access to the resource.

insufficientFeatureAccess

You do not have access to the feature.

validationError

There are requirements that have not been met.

resourceNotFound

The resource was not found.

paymentFailure

There was a problem with the payment resource.

tokenFailure

There was a problem with the token resource.

refundFailure

There was a problem with the refund resource.

customerFailure

There was a problem with the customer resource.

cardFailure

There was a problem with the card resource.

bankFailure

There was a problem with the bank resource.

transferFailure

There was a problem with the withdrawal resource.

bankLoginFailure

There was a problem with the bank login resource.

invalidTestCredentials

The test credentials used were incorrect.

Error types

The error response contains an Error Type that helps to identify broad categories of errors.

In production, the most common Error Types are the requestError and accessError. Validation errors and various payment decline errors fall under the requestError type. Attempting to access a resource using with a valid access token that does not have access to a particular resource will result in an accessError.

Type

Description

apiConnectionError

Failure to connect to the API.

apiError

General API error.

authenticationError

There was a problem with the authentication.

accessError

There was a problem accessing a resource.

requestError

There was a problem with the request.

rateLimitError

Too many requests.