Errors

All errors return JSON with a consistent shape. HTTP status codes follow standard conventions.

Error Format

{
  "error": {
    "message": "Human-readable description",
    "type": "error_type"
  }
}

Code	Type	Meaning	Action
400	invalid_request_error	Bad request body or parameters	Fix the request
401	auth_error	Invalid or missing API key	Check your key
402	billing_error	Stripe: No payment method, suspended, or over credit limit	Add/update card — do not retry
402	payment_required	MPP: Payment challenge issued. `WWW-Authenticate: Payment` header contains the challenge.	Fulfill the challenge and retry with credential
429	rate_limit_error	Too many requests	Back off; honour Retry-After header
500	server_error	Internal platform error	Retry once, then report
502	server_error	All providers failed after retries	Retry immediately (different provider selected)
503	server_error	No providers available for the model	Wait, try different model, or relax price constraints

502 — provider failure. Retry immediately — the platform selects a different provider.
503 — no providers online. Wait and retry, or try a different model.
429 — rate limited. Exponential backoff. Honour Retry-After.
402 (Stripe) — billing issue. Do not retry. Update your payment method first.
402 (MPP) — payment challenge. Retry with an Authorization: Payment credential. This is the normal MPP flow — not an error.