> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developers.clearpay.co.uk/v-2/llms.txt
> - v1: https://developers.clearpay.co.uk/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.clearpay.co.uk/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.clearpay.co.uk/_mcp/server.

# Errors

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

## HTTP status codes

| Codes       | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `200`-`299` | The request was processed successfully.                            |
| `400`-`499` | The request was not valid (e.g. a required parameter was missing). |
| `500`-`599` | The 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.

| Field            | Type    | Description                                                                                                                           |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `errorCode`      | String  | The type of error returned (e.g. `invalid_object` or `unsupported_currency`).                                                         |
| `errorId`        | String  | A unique error ID for tracking and debugging.                                                                                         |
| `message`        | String  | A human-readable message which provides more details about the error. In most cases, these messages can be displayed to the customer. |
| `httpStatusCode` | Integer | The HTTP status code                                                                                                                  |

## Example errors

### GET requests

With the exception of [Ping](https://developers.clearpay.co.uk/docs/api/reference/service-status/operations/get-a-ping), which doesn't require authentication, all GET endpoints can return the following errors:

| HTTP status            | Error code           | Description                                                                                   |
| ---------------------- | -------------------- | --------------------------------------------------------------------------------------------- |
| 401 Unauthorized       | `unauthorized`       | Invalid merchant API credentials were passed in the `Authorization` header.                   |
| 405 Method Not Allowed | `method_not_allowed` | The request was made by a method other than `GET`, `HEAD`, or `OPTIONS`.                      |
| 406 Not Acceptable     | `error`              | The 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 status                | Error code           | Description                                                                                                                          |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 400 Bad Request            | `invalid_json`       | The request body contains invalid or improperly formatted JSON.                                                                      |
| 401 Unauthorized           | `unauthorized`       | Invalid Merchant API credentials were passed in the `Authorization` header.                                                          |
| 405 Method Not Allowed     | `method_not_allowed` | The request used an unsupported HTTP method. Only `PUT` or `POST` may be allowed, depending on the endpoint. Use `OPTIONS` to check. |
| 406 Not Acceptable         | `error`              | The `Accept` header was not set to `application/json` or `*/*`.                                                                      |
| 415 Unsupported Media Type | `error`              | The request lacked a `Content-Type` header or used a value other than `application/json`.                                            |
| 500 Internal Server Error  | `error`              | Often caused by a missing or empty request body in `PUT` or `POST` requests.                                                         |