Errors & status codes
The Arena API uses standard HTTP status codes and returns errors in a consistent JSON format. Every response includes an X-Arena-Trace-ID header for debugging.
Error response format
Errors from Arena itself use this structure on every endpoint. Errors passed through from an Anthropic-format model provider on /v1/messages keep the Anthropic format, with a top-level request_id.
{
"error": {
"code": "rate_limit_exceeded",
"message": "rate limit exceeded",
"type": "invalid_request_error",
"trace_id": "req_abc123def456"
}
}| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code (see the table below) |
message | string | Human-readable error description |
type | string | Error category: invalid_request_error or server_error |
trace_id | string | Gateway trace ID for this request; include it in support requests |
Funding refusals (402)
| Error code | Meaning |
|---|---|
paid_credits_required | Promotional (router) funds remain for Arena Router, but direct models need promotional (all models) or paid funds. |
out_of_credits | No eligible funds remain. |
insufficient_credits_for_request | The remaining funds cannot cover this request, including when another request holds them. |
insufficient_credits | No eligible funds are left. Used for router requests, and for direct requests outside the paid-balance cohort. |
Read error.code to tell these apart. When the workspace can add funds, the error includes error.billing_url and the message ends with a link to add them. Show the message and any link, and wait until funds are available before retrying.
HTTP status codes
The most common codes. Always read error.code and error.message for the exact cause.
| Status | Error code | Description |
|---|---|---|
| 400 Bad Request | invalid_request / invalid_json / missing_model / unsupported_model / model_fallback_not_supported | Malformed JSON, missing or invalid fields, a model ID that does not exist, or a request that still sends the retired fallback settings. |
| 401 Unauthorized | missing_or_invalid_bearer_token / invalid_or_inactive_api_key | Missing or malformed API key, or a key that is invalid or revoked. |
| 402 Payment Required | paid_credits_required / out_of_credits / insufficient_credits_for_request / insufficient_credits | More funds are needed. See Funding refusals (402) above. |
| 403 Forbidden | organization_denied / organization_model_restricted / organization_client_restricted | Valid key, but the request is not permitted: workspace access is denied, the model is not enabled for your workspace, or a workspace limited to approved apps used another client. |
| 404 / 410 Not Found / Gone | api_path_not_found / api_route_retired | The path does not exist, or the endpoint has been retired. |
| 409 Conflict | duplicate_request_id | A request with the same ID is already being processed. |
| 413 Content Too Large | request_body_too_large | The request body is larger than 30 MB. |
| 415 Unsupported Media Type | unsupported_content_type | Send the request body as application/json. |
| 422 Unprocessable Content | model_not_allowed / billing_unbounded_request | The model is not allowed for this API key, or the request has no upper bound on its cost (set a max output tokens value). |
| 429 Too Many Requests | rate_limit_exceeded | Rate limit exceeded. See Rate limits below. |
| 500 / 502 / 503 / 504 Server and provider errors | upstream_error | The model provider failed, timed out or is unavailable. Include the X-Arena-Trace-ID in support requests. |
| 503 Service Unavailable | billing_unavailable_provider / admission_check_failed / auth_backend_unavailable | Arena could not check your key or balance. Retry after a short delay. |
Rate limits
- All of your API keys share one limit.
- A rate-limited request returns 429 before it reaches a model, so it is not charged.
- The response includes
Retry-After(seconds to wait),X-Arena-Rate-Limit-Dimension(which limit was hit),X-RateLimit-LimitandX-RateLimit-Remaining. - Repeated 429s can make
Retry-Afterlonger, so wait the full time before retrying.
Debugging with trace IDs
Every response includes an X-Arena-Trace-ID header. Include this ID when contacting support to help us investigate issues quickly.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-Arena-Trace-ID: req_abc123def456
Retry-After: 1
X-Arena-Rate-Limit-Dimension: rpm
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 0
{
"error": {
"code": "rate_limit_exceeded",
"message": "rate limit exceeded",
"type": "invalid_request_error"
}
}Retry guidance
- 429 (Rate limited): wait and retry with exponential backoff. Respect
Retry-Afterwhen present, and inspect the rate-limit headers for the limit that was hit. - 500 (Internal error): safe to retry. Include the trace ID if the issue persists.
- 502/503/504 (Provider issues): the model provider may be temporarily down. Arena does not switch models for you, so retry after a brief delay or choose a different model.
- 402 (Insufficient balance): do not retry. Add funds for your account first.
- 400/401/403/422: do not retry. Fix the request or check your API key.