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

# Errors and retries

> Handle API failures without duplicating work

Errors use a consistent JSON shape:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  }
}
```

Use `error.code` in application logic. Every response also includes `x-request-id`; log it and include it when contacting support.

## Common responses

|               HTTP | Meaning                                   | Retry?                        |
| -----------------: | ----------------------------------------- | ----------------------------- |
|                401 | Missing, invalid, or revoked key          | No                            |
|                403 | Tenant suspended                          | No                            |
|                404 | Index or document not found               | No                            |
|                422 | Invalid request or document limit reached | No                            |
|                429 | Rate, concurrency, or monthly usage limit | Usually; inspect `error.code` |
| 500, 502, 503, 504 | Temporary service failure                 | Yes, with a limit             |

Retry temporary network failures and the retryable statuses above with exponential backoff and jitter. Honor `Retry-After` when present. Stop after a small number of attempts; six total attempts is a reasonable upper bound.

Do not keep retrying `usage_limit_exceeded`. Wait for the allowance to reset or contact support.

## Safe retries

* Document upserts are safe to repeat because `doc_id` replaces existing content. Still inspect `failed` after every HTTP 200.
* Document deletion, list, usage, search, and score requests are safe to repeat.
* Index creation is not safely repeatable. After a timeout, list indexes and check for the intended name before trying again.

Set finite client timeouts. A timeout does not prove that the server abandoned the request.