Error codes

Updated 9/19/2026

Failed requests return a unified error structure; the code field is a machine-readable code.

Error code table

HTTP	code	Billed	Description
400	`invalid_request`	No	Invalid request parameters
401	`invalid_api_key`	No	Missing or invalid API key
402	`insufficient_balance`	No	Insufficient balance — top up
403	`model_not_allowed`	No	Model not authorized for this key
429	`rate_limit_exceeded`	No	Rate limited — retry later
500	`billing_settlement_error`	Async reconcile	Billing settlement failure
502	`upstream_error`	Usually no	Upstream service error
503	`model_provider_unavailable`	No	Model service temporarily unavailable
504	`upstream_timeout`	Usually no	Upstream timeout

Troubleshooting

401: confirm the Authorization: Bearer value is the full sk-live-* secret and the key is not revoked.
402: top up in the console.
429: lower concurrency, or wait for retry-after before retrying.
5xx: retry later; if it persists, contact support with the request_id.

Error example

{
  "error": {
    "message": "insufficient balance",
    "type": "request_error",
    "code": "insufficient_balance",
    "param": null,
    "request_id": "req_8f2a…c91d"
  }
}