# Errors

Every error uses one envelope, always with the correct HTTP status:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "echo_too_long",
    "message": "echo must be at most 500 characters.",
    "param": "echo",
    "docs_url": "https://example.com/docs/errors",
    "request_id": "req_8f2c1ab90d3e44aa55bb66cc"
  }
}
```

Envelope fields:
- `type` (string, required), one of: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `conflict_error`, `api_error`
- `code` (string, required)
- `message` (string, required)
- `param` (string)
- `docs_url` (string, required). Documentation page for this error code.
- `request_id` (string, required)

`error.type` is a finite enum:
- `authentication_error`
- `permission_error`
- `invalid_request_error`
- `rate_limit_error`
- `conflict_error`
- `api_error`

Error responses defined in the spec:
- **Unauthorized**: Missing, malformed, invalid, or revoked API key. (example code: `api_key_invalid`)
- **PermissionDenied**: The key is valid but lacks the required scope or flavor. (example code: `secret_key_required`)
- **NotFound**: No such resource (or the id is malformed). (example code: `resource_missing`)
- **InvalidRequest**: The request body or parameters are invalid. (example code: `echo_too_long`)
- **Conflict**: Idempotency conflict (key reused with a different payload, or original still in flight). (example code: `idempotency_key_reused`)
- **RateLimited**: Too many requests. Honor `Retry-After` and the `RateLimit-*` headers. (example code: `rate_limit_exceeded`)

## Retries

React to statuses, not message text:

- For `429`, wait `Retry-After` seconds, then retry the identical request.
- For `5xx`, retry with exponential backoff and a capped attempt count; reuse the same `Idempotency-Key` on writes so a retry can never double-apply.
- After a network timeout on a write, retry with the **same** `Idempotency-Key`; the reply is the persisted original response, whatever happened.
- `409` with `idempotency_key_reuse` means you reused a key with a different payload; change the key, not the payload.
- For other `4xx` errors, do not retry; fix the request. The `param` field names the offending input.

Error messages are written to be actionable: they state what was wrong,
which `param` caused it, and include `docs_url` pointing at this page.
On `429`, honor `Retry-After` and the `RateLimit-*` headers before retrying.
On `409` idempotency conflicts, change the `Idempotency-Key`, not the payload.

