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

# Errors

> HTTP status codes and error shapes returned by the API.

The API uses conventional HTTP status codes and returns a JSON body with an `error`
message (and often a `message` field with more detail).

## Status codes

| Code          | Meaning                                                             |
| ------------- | ------------------------------------------------------------------- |
| `200` / `201` | Success                                                             |
| `400`         | Bad request — validation failed or a required field is missing      |
| `401`         | Unauthorized — missing or invalid credential                        |
| `403`         | Forbidden — authenticated, but not allowed for this resource        |
| `404`         | Not found                                                           |
| `409`         | Conflict — the resource already exists or is in a conflicting state |
| `429`         | Too many requests — you are being rate limited                      |
| `5xx`         | Server error — safe to retry with backoff                           |

## Error shape

```json theme={null}
{
  "error": "Bad Request",
  "message": "amount is required"
}
```

## Handling errors

<AccordionGroup>
  <Accordion title="401 vs 403">
    `401` means the credential itself was rejected — check the header and the key.
    `403` means the credential is valid but not permitted for that action.
  </Accordion>

  <Accordion title="409 conflict">
    Common on idempotent create operations (e.g. creating a wallet that already exists
    for a customer + network). Treat it as "already done" and read the existing resource.
  </Accordion>

  <Accordion title="429 and 5xx">
    Retry with exponential backoff and jitter. Never retry a non-idempotent write
    without a stable reference/idempotency key.
  </Accordion>
</AccordionGroup>

<Note>
  Always key your business logic off the HTTP status code first, then the `error` string.
  Message wording may change; status codes are stable.
</Note>