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

# API errors and status codes

> AlgoVoi API errors: the JSON error envelope, HTTP status mapping (400/401/402/403/409/422/429), common error codes, and 4xx vs 5xx retry behaviour.

## The envelope

All errors share the same JSON shape:

```json theme={null}
{
  "error": "machine_readable_code",
  "message": "Human-readable explanation",
  "request_id": "req_abc123…",
  "...": "additional context fields where useful"
}
```

`error` is a stable string suitable for branching in your code. `message` is human-readable and may change wording across releases. `request_id` matches the `X-Request-Id` header on the response.

## HTTP status codes

| Status  | Meaning           | Examples                                                                     |
| ------- | ----------------- | ---------------------------------------------------------------------------- |
| **200** | Success           | Normal response                                                              |
| **201** | Created           | After `POST /v1/payment-links`                                               |
| **400** | Bad request       | Invalid JSON, missing required field                                         |
| **401** | Unauthorised      | Missing or invalid API key                                                   |
| **402** | Payment Required  | x402 / MPP / AP2 challenge response                                          |
| **403** | Forbidden         | Key lacks the required scope                                                 |
| **404** | Not found         | Unknown checkout token, unknown resource                                     |
| **409** | Conflict          | Duplicate idempotency key, double-spend on a tx\_id                          |
| **422** | Unprocessable     | Schema is valid but the action can't proceed (e.g. KYC required for mainnet) |
| **429** | Too many requests | Rate-limited. See [Rate limits](/api-reference/rate-limits).                 |
| **5xx** | Server error      | Gateway, facilitator, or upstream chain RPC unavailable                      |

## Common error codes

| Code                        | When                                                    | HTTP |
| --------------------------- | ------------------------------------------------------- | ---- |
| `invalid_api_key`           | Bearer token is missing or doesn't match a known key    | 401  |
| `tenant_id_mismatch`        | The `X-Tenant-Id` header doesn't match the key's tenant | 403  |
| `kyb_required_for_mainnet`  | Trial tenant tried a live network                       | 422  |
| `payment_link_expired`      | Customer tried to verify a checkout past its TTL        | 422  |
| `payment_link_already_paid` | Same checkout verified twice                            | 409  |
| `payment_not_verified`      | Facilitator couldn't confirm the on-chain transaction   | 422  |
| `self_payment_blocked`      | Payer address equals payout address                     | 403  |
| `unsupported_network`       | The chain isn't enabled for this tenant                 | 400  |
| `cross_tenant_replay`       | Tx ID already used by a different tenant                | 422  |
| `rate_limited`              | Per-tenant or per-IP rate limit hit                     | 429  |

## Behaviour expectations

* **4xx errors** indicate a problem the caller can fix. Don't retry without changing something.
* **5xx errors** are server-side. The client should retry with backoff. Default Retry-After is 30 seconds.
* **402 challenges** are not errors per se. They're the start of an x402 / MPP / AP2 payment flow. See the protocol pages.

## See also

* [API introduction](/api-reference/introduction) for the request envelope
* [Rate limits](/api-reference/rate-limits) for 429 specifics
* [Authentication](/api-reference/authentication) for 401 versus 403