Foundations

Errors

The Clearpay API uses conventional HTTP status codes and returns error responses in JSON format.

HTTP status codes

CodesDescription
200-299The request was processed successfully.
400-499The request was not valid (e.g. a required parameter was missing).
500-599The request could not be processed for an unexpected reason.

Error fields

Returns a JSON object and an appropriate HTTP status code.

Please note that the human-readable textual messages included within the error object are improved over time. For validation and mapping purposes, please use the error code or HTTP status code values.

FieldTypeDescription
errorCodeStringThe type of error returned (e.g. invalid_object or unsupported_currency).
errorIdStringA unique error ID for tracking and debugging.
messageStringA human-readable message which provides more details about the error. In most cases, these messages can be displayed to the customer.
httpStatusCodeIntegerThe HTTP status code

Example errors

GET requests

With the exception of Ping, which doesn’t require authentication, all GET endpoints can return the following errors:

HTTP statusError codeDescription
401 UnauthorizedunauthorizedInvalid merchant API credentials were passed in the Authorization header.
405 Method Not Allowedmethod_not_allowedThe request was made by a method other than GET, HEAD, or OPTIONS.
406 Not AcceptableerrorThe request included an Accept header for something other than application/json or */*.

POST / PUT requests

All PUT and POST endpoints can return any of the following errors:

HTTP statusError codeDescription
400 Bad Requestinvalid_jsonThe request body contains invalid or improperly formatted JSON.
401 UnauthorizedunauthorizedInvalid Merchant API credentials were passed in the Authorization header.
405 Method Not Allowedmethod_not_allowedThe request used an unsupported HTTP method. Only PUT or POST may be allowed, depending on the endpoint. Use OPTIONS to check.
406 Not AcceptableerrorThe Accept header was not set to application/json or */*.
415 Unsupported Media TypeerrorThe request lacked a Content-Type header or used a value other than application/json.
500 Internal Server ErrorerrorOften caused by a missing or empty request body in PUT or POST requests.