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.

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

Error

ParameterDescription
nameThe HTTP status code name. See below for more information.
statusThe HTTP status code. See below for more information.
typeThe error type. See below for more information.
descriptionThe description for the error type.
detailsAn embedded details object. See below for more information.
refA unique reference code given to each error.

Details

ParameterDescription
codeThe error detail code. See below for more information.
descriptionThe description for the error detail code.
detailCodeA code given to describe the specific details of the error.
parameterThe parameter associated with the error (if available).
valueThe parameter values associated with the error (if available).
explanationA 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 CodeStatus NameDescription
200SuccessThe request was successful.
204No ContentEmpty response.
400Bad RequestThe request failed, possibly due to a malformed request.
401UnauthorizedAccess to the resource is denied
402Request FailedThe request was not successful despite being a valid request.
404Not FoundThe resource was not found
422Unprocessable EntityThe request failed, possibly due to validation problems.
429Too Many RequestsYou have performed too many requests
500Internal Server ErrorSomething went wrong on the Paystand end.
503Service UnavailableThe 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 CodeDescription
apiErrorThe request failed due to an API error
insufficientResourceAccessYou do not have access to the resource.
insufficientFeatureAccessYou do not have access to the feature.
validationErrorThere are requirements that have not been met.
resourceNotFoundThe resource was not found.
paymentFailureThere was a problem with the payment resource.
tokenFailureThere was a problem with the token resource.
refundFailureThere was a problem with the refund resource.
customerFailureThere was a problem with the customer resource.
cardFailureThere was a problem with the card resource.
bankFailureThere was a problem with the bank resource.
transferFailureThere was a problem with the withdrawal resource.
bankLoginFailureThere was a problem with the bank login resource.
invalidTestCredentialsThe 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.

TypeDescription
apiConnectionErrorFailure to connect to the API.
apiErrorGeneral API error.
authenticationErrorThere was a problem with the authentication.
accessErrorThere was a problem accessing a resource.
requestErrorThere was a problem with the request.
rateLimitErrorToo many requests.