Appearance
Errors & retries ā
Every error has the same shape, whatever the provider:
json
{
"error": {
"type": "rate_limited",
"code": "rpm_exceeded",
"message": "Rate limit reached: 300 requests per minute.",
"provider": null,
"request_id": "req_6b1cā¦"
}
}Branch on type (or the SDK's error class) and code. Messages may change; type and code won't. Include request_id when contacting support.
| HTTP | type | Common codes | Retry? |
|---|---|---|---|
| 400 | invalid_request | invalid_json, missing_model, wrong_model_type, unsupported_model_feature, unsupported_feature (Anthropic features not offered yet), too_many_completions (n > 8), provider_rejected_request | No: fix the request |
| 401 | authentication | missing_api_key, invalid_api_key | No |
| 402 | insufficient_credits | insufficient_credits | After adding credits |
| 403 | permission_denied | scope_missing, account_suspended | No |
| 404 | not_found | model_not_found, route_not_found | No |
| 429 | rate_limited | rpm_exceeded, tpm_exceeded, daily_spend_limit_reached | Yes, after Retry-After |
| 502 | provider_error | provider_error | Yes, with backoff |
| 503 | service_unavailable | no_provider_available, provider_overloaded | Yes, with backoff |
| 504 | timeout | provider_timeout | Yes, with backoff |
Provider failures have usually already been retried on other providers before you see them, so a 502/503 means every eligible provider failed.
Retrying ā
The official SDKs retry connection errors, 408, 409, 429 and 5xx twice by default with exponential backoff and jitter, honouring Retry-After. If you call the API directly, do the same, and don't retry 4xx errors other than 408, 409 and 429.
Requests that fail are not charged. Credits held for a failed request are released immediately.