Common errors

Updated

When a call fails, check the HTTP status and error code, then use the table below. Error messages follow the Accept-Language header (zh-CN or en-US).

Error formats

API Format
OpenAI-compatible /v1/* {"error": {"message", "type", "code", "request_id"}}
Anthropic-compatible {"type": "error", "error": {"type", "message"}}, with no machine-readable code
Gemini-compatible {"error": {"code", "message", "status"}}
Platform API /api/v1/*, media tasks {"code", "message", "request_id", "details"}

Include the request_id when contacting support.

Common error codes

Code HTTP Cause What to do
auth.invalid_key 401 Wrong, paused, expired or revoked key, or the key was put in the URL Check the key and the request header
auth.forbidden 403 The model is not in the key's allowed models Update the key's allowed models
key.ip_denied 403 Source IP is not on the key's allowlist Update the IP allowlist
key.spend_limit 402 The key hit its daily or monthly spend limit (billing.key_limit_exceeded in the OpenAI format) Raise the limit or wait for the period to roll over
billing.insufficient_credit 402 Balance cannot cover the call's estimated cost Top up
billing.in_arrears 403 The account is in arrears Top up to clear the arrears
rate.limited 429 Request rate limit exceeded Back off and retry
concurrency.exceeded 429 Too many requests in progress Wait for running requests to finish
model.unavailable 404 Unknown, in maintenance, retired, or lacking the capability this endpoint needs Check the model ID and capabilities
routing.not_applied 409 The model has no usable supply route right now Retry later or use another model
upstream.unavailable 503 The upstream failed or timed out Retry later; failed calls are free
account.restricted 403 API calls are paused for the account Check notifications or open a ticket
content.prohibited.* 403 The request hit a content rule Change the content, or appeal via the link in details

Retrying

  • 429 and 503 are retryable; use exponential backoff with a retry cap.
  • 401, 402, 403 and 404 will not succeed on retry; fix the cause first.
  • Non-streaming requests time out after 120 seconds in total, so use streaming for long outputs.

FAQ

How should I retry a 429?
Both rate.limited and concurrency.exceeded are retryable. Use exponential backoff with a retry cap and reduce concurrent requests.
Am I charged for upstream.unavailable?
No. Calls that fail or time out upstream count as failed and are free; retry later.
Why is there no error code in the Anthropic format?
Anthropic error bodies carry only a type and message. Use the OpenAI-compatible API if you need machine-readable codes.