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

# Errors

> Error response shape, status codes, retry behavior, and logging guidance.

Errors use a JSON envelope with a stable upper-case code and human-readable message.

```json theme={null}
{
  "status": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "missing X-Api-Key header"
  }
}
```

Do not parse `message` for control flow. Use HTTP status and `error.code` for programmatic handling.

## Common Status Codes

| Status | Meaning                               | Action                                                         |
| ------ | ------------------------------------- | -------------------------------------------------------------- |
| `400`  | Invalid request                       | Fix parameters, filters, enum values, or body fields           |
| `401`  | Missing or invalid API key            | Check `X-Api-Key`                                              |
| `402`  | Insufficient available balance        | Reconcile balances and reduce or defer the request             |
| `403`  | Access or account requirement not met | Confirm key access and account readiness                       |
| `404`  | Resource not found                    | Verify the public identifier and account context               |
| `409`  | Conflict                              | Check idempotency, duplicate intent, or current resource state |
| `422`  | Valid JSON that cannot be processed   | Correct the destination or business input                      |
| `429`  | Too many requests                     | Back off and retry later                                       |
| `503`  | Service temporarily unavailable       | Use bounded backoff and preserve retry safety                  |

## Retry Guidance

| Class | Retry?             | Notes                                                                     |
| ----- | ------------------ | ------------------------------------------------------------------------- |
| `400` | No                 | The request is malformed or semantically invalid                          |
| `401` | No                 | Fix credentials or environment                                            |
| `402` | No                 | Restore available balance or submit a smaller valid request               |
| `403` | No                 | Fix key access or account readiness                                       |
| `404` | Usually no         | Retry only if you expect eventual visibility after a recent action        |
| `409` | Depends            | For idempotency conflicts, read the existing order or create a new intent |
| `422` | No                 | Correct the request's business input                                      |
| `429` | Yes, after backoff | Slow down the caller and keep idempotency keys stable for order writes    |
| `5xx` | Yes, bounded       | Retry with backoff while preserving the operation's idempotency rules     |

For a signed withdrawal retry, keep the exact body and its business
`idempotency_key`, then generate a new timestamp, nonce, and signature for the
new HTTP attempt. See [Withdrawals](/docs/withdrawals). Do not apply generic
retry logic that changes the withdrawal body.

## Required Headers

Use `X-Api-Key` on authenticated endpoints. Use `Content-Type: application/json` on JSON writes. Use `Idempotency-Key` on order create, cancel, and replace requests.