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

# Errors

> One envelope on every failure. Branch on code, show message.

## Envelope

```http theme={null}
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="arena", error="invalid_token", error_description="API key is invalid, revoked or expired."
Cache-Control: no-store

{
  "error": {
    "code": "invalid_token",
    "message": "API key is invalid, revoked or expired."
  }
}
```

| Field | |
| - | - |
| `error.code` | Stable machine token. Branch on this. |
| `error.message` | Human sentence. May change; never parse it. |
| `error.retryAfterSeconds` | On every `429`. Equals the `Retry-After` header. |

Status codes mean what HTTP says. If you get a `code` you do not recognize, handle it by its HTTP status.

## Codes

| Status | Code | Meaning | Retry |
| - | - | - | - |
| 400 | `invalid_request` | Malformed body or parameter. The message names the field. | No |
| 401 | `unauthorized` | No credential presented. | No |
| 401 | `invalid_token` | Key is malformed, unknown, revoked or expired. | No |
| 401 | `session_required` | An API key was sent to key management. Use a session. | No |
| 403 | `insufficient_scope` | Key lacks the endpoint's scope. Create a key with it. | No |
| 403 | `guest_account` | Key management needs a signed-in Google or Apple account. | No |
| 403 | `scope_not_available` | Scope exists but is not issued yet (`trade:write`). | No |
| 403 | `venue_data_off` | Venue prices are not served on the keyed API yet. | No |
| 404 | `route_not_found` | No such path under `/api/v1`. Planned endpoints answer this. | No |
| 404 | `key_not_found` | No active key with that id on this account. | No |
| 404 | `trader_not_found` | No trader has that id or display name. | No |
| 404 | `account_not_found` | The key's account has no balance yet; it gets one with its first trade. | No |
| 404 | `instrument_not_found` | No public instrument has that id or slug. | No |
| 404 | `game_not_found` | No game with a public instrument has that id or slug. | No |
| 405 | `method_not_allowed` | Path does not serve this method. See the `Allow` header. | No |
| 409 | `key_limit_reached` | Ten active keys already. Revoke one first. | No |
| 429 | `rate_limited` | Over the plan's per-minute limit. | After `Retry-After` |
| 429 | `quota_exceeded` | Over the plan's monthly quota. | After `Retry-After` |
| 429 | `key_creation_limited` | Twenty keys created in 24 hours, rotations included. | After `Retry-After` |
| 500, 503 | `internal_error` | Server-side failure, or the key or data could not be read right now. The key may be fine. | With backoff |

Quote the `X-Request-Id` response header when contacting [support](https://arena-predictions.com/support).