{
"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. |