Skip to content

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.

HTTPtypeCommon codesRetry?
400invalid_requestinvalid_json, missing_model, wrong_model_type, unsupported_model_feature, unsupported_feature (Anthropic features not offered yet), too_many_completions (n > 8), provider_rejected_requestNo: fix the request
401authenticationmissing_api_key, invalid_api_keyNo
402insufficient_creditsinsufficient_creditsAfter adding credits
403permission_deniedscope_missing, account_suspendedNo
404not_foundmodel_not_found, route_not_foundNo
429rate_limitedrpm_exceeded, tpm_exceeded, daily_spend_limit_reachedYes, after Retry-After
502provider_errorprovider_errorYes, with backoff
503service_unavailableno_provider_available, provider_overloadedYes, with backoff
504timeoutprovider_timeoutYes, 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.