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

All error responses follow this structure:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "rate limit exceeded",
    "type": "invalid_request_error",
    "param": null
  }
}

Field	Type	Description
`code`	string	Machine-readable error code (see table below)
`message`	string	Human-readable error description
`type`	string	Error category for grouping (e.g., authentication_error, server_error)
`param`	string \| null	The field that caused the error (when applicable)

HTTP status codes

Status	Error code	Description
400 Bad Request	`invalid_request`	Malformed JSON, missing required fields, or invalid field values.
401 Unauthorized	`unauthorized`	Missing or invalid API key in the Authorization header.
402 Payment Required	`insufficient_credits`	Account credit balance is exhausted. Top up your balance to continue.
403 Forbidden	`forbidden`	Valid key but insufficient permissions (e.g., key not owned by you).
422 Unprocessable Content	`model_not_allowed`	The request is valid, but the selected model is not allowed for this API key.
413 Content Too Large	`request_too_large`	Request body exceeds the 10 MB limit.
429 Too Many Requests	`rate_limit_exceeded`	Rate limit exceeded.
500 Internal Server Error	`internal_error`	Unexpected server error. Include the X-Arena-Trace-ID in support requests.
502 Bad Gateway	`provider_unavailable`	Gateway could not reach the upstream provider.
503 Service Unavailable	`provider_unavailable`	Provider not configured or temporarily unavailable.

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-After when 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 (Provider issues) — the upstream model provider may be temporarily down. Retry after a brief delay, or switch to a routing mode to let Arena pick an available model.
402 (Insufficient credits) — do not retry. Top up your account balance first.
400/401/403/422 — do not retry. Fix the request or check your API key.