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.

Error

Details

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.

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.

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.