Docs
Error handling
There are two kinds of error: the ones the gateway blocked on a verdict, and the ones a provider returned. Tell them apart with error.source in the response.
Code table
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed body or unknown parameter |
| 401 | invalid_api_key | Missing, revoked or malformed key |
| 403 | policy_blocked | Organization policy, key scope or IP rule |
| 402 | budget_exceeded | Key budget or balance exhausted |
| 404 | model_not_found | Unknown model or route path |
| 409 | idempotency_conflict | Key reused with a different body |
| 429 | rate_limited | Provider or gateway throttling |
| 502 | provider_error | Upstream provider failed |
| 504 | provider_timeout | Upstream provider timed out |
Retries
Retry 429 and 5xx only. Use exponential backoff with jitter, and capping at three attempts is the safe default. 400 and 403 return the same result however many times you try.
Idempotency
If a request could be sent twice, include an Idempotency-Key header. Within 24 hours, a repeat of the same key returns the original response and is not billed again.