API reference

Errors

Errors use standard HTTP status codes and an OpenAI-style error body on both surfaces.

json

{
  "error": {
    "type": "insufficient_balance",
    "message": "Balance $0.02 is below the estimated cost of this request.",
    "code": 402
  }
}

Codes

Status	Type	What to do
400	`invalid_request`	Fix the request body. The message names the field.
401	`invalid_api_key`	Check the key, or create a new one.
402	`insufficient_balance`	Top up from Balance.
404	`model_not_found`	Use an id from `GET /v1/models`.
429	`rate_limited`	Wait for `retry-after` seconds.
502	`upstream_error`	All upstreams for this model failed. Retry, or pick another model.
503	`overloaded`	Temporary. Retry with backoff.

Retries

Retry 429, 502 and 503 with exponential backoff. Don't retry 400, 401, 402 or 404 without changing something first.