Docs

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"
  }
}
FieldTypeDescription
codestringMachine-readable error code (see the table below)
messagestringHuman-readable error description
typestringError category: invalid_request_error or server_error
trace_idstringGateway trace ID for this request; include it in support requests

Funding refusals (402)

Error codeMeaning
paid_credits_requiredPromotional (router) funds remain for Arena Router, but direct models need promotional (all models) or paid funds.
out_of_creditsNo eligible funds remain.
insufficient_credits_for_requestThe remaining funds cannot cover this request, including when another request holds them.
insufficient_creditsNo 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.

StatusError codeDescription
400 Bad Requestinvalid_request / invalid_json / missing_model / unsupported_model / model_fallback_not_supportedMalformed JSON, missing or invalid fields, a model ID that does not exist, or a request that still sends the retired fallback settings.
401 Unauthorizedmissing_or_invalid_bearer_token / invalid_or_inactive_api_keyMissing or malformed API key, or a key that is invalid or revoked.
402 Payment Requiredpaid_credits_required / out_of_credits / insufficient_credits_for_request / insufficient_creditsMore funds are needed. See Funding refusals (402) above.
403 Forbiddenorganization_denied / organization_model_restricted / organization_client_restrictedValid 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 / Goneapi_path_not_found / api_route_retiredThe path does not exist, or the endpoint has been retired.
409 Conflictduplicate_request_idA request with the same ID is already being processed.
413 Content Too Largerequest_body_too_largeThe request body is larger than 30 MB.
415 Unsupported Media Typeunsupported_content_typeSend the request body as application/json.
422 Unprocessable Contentmodel_not_allowed / billing_unbounded_requestThe 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 Requestsrate_limit_exceededRate limit exceeded. See Rate limits below.
500 / 502 / 503 / 504 Server and provider errorsupstream_errorThe model provider failed, timed out or is unavailable. Include the X-Arena-Trace-ID in support requests.
503 Service Unavailablebilling_unavailable_provider / admission_check_failed / auth_backend_unavailableArena 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-Limit and X-RateLimit-Remaining.
  • Repeated 429s can make Retry-After longer, 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-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/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.