Errors

Every error code, its HTTP status, and which ones to retry.

Errors use the OpenAI JSON shape, so existing SDK error handling works unchanged:

{
  "error": {
    "message": "Model 'nope/never' does not exist or is not available",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}

type is invalid_request_error when the fix is on your side, api_error otherwise. code is the machine-readable taxonomy:

Code	HTTP	Retry?	Meaning
`invalid_request`	400	no	malformed body, or a feature this model doesn't support (the message names it)
`model_not_found`	400	no	unknown or unavailable model id
`context_length_exceeded`	400	no	prompt too long for the model's window
`invalid_api_key`	401	no	missing, malformed, disabled or expired key
`insufficient_credits`	402	after top-up	balance is zero or below
`model_not_allowed`	403	no	free tier or key allowlist blocks this model (the message says which models work)
`key_limit_exceeded`	403	no	this key's spend cap is reached
`account_suspended`	403	no	contact support
`rate_limited`	429	yes, after `Retry-After`	per-key rate limit, or the upstream provider throttling
`too_many_concurrent`	429	yes, when a stream finishes	per-key concurrent-stream limit
`provider_overloaded`	502	yes, with backoff	upstream provider is overloaded
`provider_error`	502	yes, with backoff	upstream provider failed
`upstream_auth`	502	yes, briefly	gateway-side provider configuration issue (our pager is already ringing)
`gate_unavailable`	503	yes, after `Retry-After`	billing gate briefly unreachable — never results in a free or lost charge
`timeout`	504	yes	upstream timed out

Guidance:

Retry only what the table marks retryable, with exponential backoff and jitter; honor Retry-After when present.
4xx never fixes itself — don't retry it in a loop.
Failures after streaming has started arrive in-band with finish_reason: "error" — see Streaming.
One retry against an overloaded provider is already performed inside the gateway before you ever see provider_overloaded.

Include the X-Gopuram-Request-Id response header when reporting anything — it pinpoints the exact request in our logs (which contain metering data only, never your prompts).