Skip to content
alpharouter

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

StatuscodeMeaning
400invalid_requestMalformed body or unknown parameter
401invalid_api_keyMissing, revoked or malformed key
403policy_blockedOrganization policy, key scope or IP rule
402budget_exceededKey budget or balance exhausted
404model_not_foundUnknown model or route path
409idempotency_conflictKey reused with a different body
429rate_limitedProvider or gateway throttling
502provider_errorUpstream provider failed
504provider_timeoutUpstream 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.