Errors

Errors use OpenAI’s envelope, so existing SDK error handling works unchanged.

Envelope

{
  "error": {
    "message": "Insufficient credits",
    "type": "insufficient_quota",
    "param": null,
    "code": null
  }
}

HTTP	`type`	Meaning
`400`	`invalid_request_error`	Bad input (unsupported model, bad params).
`401`	`authentication_error`	Missing / malformed key.
`403`	`permission_error`	Key disabled, expired, or out of scope.
`402`	`insufficient_quota`	Out of credits or spend cap reached.
`404`	`not_found_error`	Unknown route / resource.
`429`	`rate_limit_error`	Rate limit or TPM exceeded — back off.
`503`	`service_unavailable`	No healthy route is available — safe to retry.
`500`	`server_error`	Unexpected; internal details are never leaked.

429 / 503 → retry with exponential backoff and jitter. For chat completions, use an Idempotency-Key to guard duplicate billing.
402 → top up credits or raise the spend cap.
400 / 401 / 403 → fix the request; retrying won’t help.

On any failed call, the pre-charged estimate is automatically refunded — you’re only billed for work that succeeded.

The Messages surface uses a different SDK-compatible error wrapper; see Messages errors.