Error codes

Errors use the OpenAI shape. Match on code, not on the message text.

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "insufficient_balance"
  }
}

Code	HTTP	Meaning
invalid_api_key	401	The API key is wrong, revoked, blocked or expired.
insufficient_balance	402	Balance is too low. Top up and try again.
plan_quota_exhausted	429	The plan allowance is used up.
rate_limit_exceeded	429	Too many requests. Try again in a moment.
model_not_found	404	The model does not exist or this key may not use it.
unsupported_endpoint	404	This endpoint is not available.
not_found	404	Not found.
request_too_large	413	The request is too large.
context_length_exceeded	400	The input is longer than the model context.
content_policy_violation	400	The request content was rejected by content policy.
upstream_unavailable	503	The model service is unavailable. Try again later.
upstream_timeout	504	The model took too long to answer. Try again.
turnstile_failed	400	The security check failed. Try again.
terms_required	400	Agree to the Terms of Service and Privacy Policy to sign up.

How to respond

• invalid_api_key: check the key in the console. Do not retry unchanged.
• insufficient_balance: add balance, or lower max_tokens, because cost is reserved first.
• plan_quota_exhausted: the plan allowance is used up and the plan is set to reject. Wait for the allowance to refill or change plan.
• rate_limit_exceeded: wait a moment, then retry. Use longer and longer pauses. See Rate limits.
• upstream_unavailable and upstream_timeout: temporary. Retry after a few seconds.
• context_length_exceeded: shorten the prompt or choose a model with a larger context.