> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centsless.org/llms.txt
> Use this file to discover all available pages before exploring further.

# API error codes and responses

> The Centsless API returns standard HTTP status codes with a JSON body containing a machine-readable error code and a human-readable message. Learn what each status code means.

Centsless returns standard HTTP status codes on every response. When a request fails, the response body is a JSON object with two fields: `error`, a machine-readable code you can match against in your integration, and `message`, a human-readable description suitable for logging.

## Error response structure

Every error response follows this schema:

```json theme={null}
{
  "error": "ERROR_CODE",
  "message": "Human-readable description"
}
```

## HTTP status codes

| Status                      | Meaning                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `200 OK`                    | Request succeeded.                                                                                  |
| `201 Created`               | Resource created successfully (for example, a new API key).                                         |
| `400 Bad Request`           | Validation error — a required field is missing or a field value is not a valid enum option.         |
| `401 Unauthorized`          | The `x-api-key` header is missing or the key is invalid.                                            |
| `403 Forbidden`             | The API key is valid but lacks permission for the requested endpoint.                               |
| `404 Not Found`             | The requested transaction or resource does not exist.                                               |
| `429 Too Many Requests`     | You have exceeded the rate limit for your API key (1,000 req/hr sandbox, 10,000 req/hr production). |
| `500 Internal Server Error` | An unexpected error occurred on the server. Retry with exponential backoff.                         |

## Common error codes

### `UNAUTHORIZED` — 401

Returned when the `x-api-key` header is absent or the key has been revoked.

```json theme={null}
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

### `FORBIDDEN` — 403

Returned when your key is valid but is not scoped for the endpoint you called. For example, a merchant key calling an admin-only endpoint.

```json theme={null}
{
  "error": "FORBIDDEN",
  "message": "Insufficient permissions for this endpoint"
}
```

### `VALIDATION_ERROR` — 400

Returned when a required field is missing from the request body or a field value falls outside the allowed enum.

```json theme={null}
{
  "error": "VALIDATION_ERROR",
  "message": "merchant_id is required"
}
```

### `NOT_FOUND` — 404

Returned when you reference a transaction ID or other resource that does not exist.

```json theme={null}
{
  "error": "NOT_FOUND",
  "message": "Transaction not found"
}
```

<Tip>
  The `compliance_status` field in transaction responses (`PASS`, `WARN`, or `FAIL`) signals jurisdiction compliance issues. These are separate from HTTP errors — a transaction can return `200 OK` with a `compliance_status` of `WARN` or `FAIL`. Check this field in every transaction response alongside the HTTP status.
</Tip>