Errors

Errors use the OpenAI format, so SDKs raise them as normal API errors. Use code to decide what to do.

{
  "error": {
    "message": "Insufficient balance for this request. Add funds or lower max_tokens.",
    "type": "insufficient_funds",
    "param": null,
    "code": "insufficient_funds"
  }
}

Status	Code	What to do
400	`invalid_request`	Fix the request; the message says what is wrong.
401	`invalid_api_key`	Check the key and the `Authorization: Bearer` header. Revoked keys answer this.
402	`insufficient_funds`	Top up, or lower `max_tokens` so the request fits your balance.
402	`monthly_budget_exceeded`	This key reached its monthly limit. Raise the limit or wait for next month.
403	`account_frozen`	The account is frozen pending review of a payment dispute. Contact support.
403	`key_paused`	Resume the key on the API keys page.
404	`model_not_found`	Check the model name against `GET /v1/models`.
409 / 422	`idempotency_key_*`	See safe retries.
413	`request_too_large`	Send a smaller request.
429	`rate_limit_exceeded`	Too many requests for this key. Wait for `Retry-After` seconds.
429	`too_many_inflight`	Too many requests running at once for your account. Retry when some finish.
429	`upstream_rate_limited`	The model provider is busy. Retry after `Retry-After`. Not charged.
502	`upstream_error`	The model provider failed. Retry. Not charged.
503	`service_unavailable`, `upstreams_unavailable`	Temporarily unavailable. Retry after `Retry-After`. Not charged.
504	`upstream_timeout`	The provider timed out. Retry, perhaps with a smaller `max_tokens`. Not charged.

Retrying

Retry 429, 502, 503 and 504 with a short, growing delay, and respect Retry-After. Do not retry 400, 401, 402, 403 or 404 without changing something first. Add an Idempotency-Key so a retry never runs a request twice.

Questions? Email [email protected] with your X-Request-Id.