Errors and retries
Last updated September 1, 2026
Error types, failover behavior, client retries, and billing rules for the Amux API.
Amux returns an error shape compatible with the protocol you use. Every error includes a request_id that support can use to locate the request.
Error types
| Type | HTTP | Attribution | Gateway failover |
|---|---|---|---|
| invalid_request | 400 | Caller | No |
| context_length_exceeded | 400 | Caller | No |
| authentication | 401 | Caller | No |
| insufficient_credits | 402 | Caller | No |
| permission_denied | 403 | Caller | No |
| content_policy_violation | 403 | Caller | No |
| request_timeout | 408 | Upstream | Yes |
| rate_limit_exceeded | 429 | Caller | No |
| provider_rate_limited | 502 | Upstream | Yes |
| provider_error | 502 | Upstream | Yes |
| provider_overloaded | 502 | Upstream | Yes |
| provider_account_issue | 502 | Upstream | No |
| not_found | 404 | Caller | No |
| no_available_provider | 503 | Platform | No |
| overloaded | 503 | Platform | No |
| internal_error | 500 | Platform | No |
Attribution identifies where an error originated:
- Caller: the request, authentication, balance, or usage limit needs attention. Changing providers cannot resolve it
- Upstream: a provider timed out, was rate limited or overloaded, or returned an invalid response
- Platform: Amux cannot process the request temporarily, or no provider is currently available
“Gateway failover” indicates whether Amux may try another available provider before the response begins. It does not mean that the client retries automatically, and it does not guarantee that another provider is available.
Client retries
Use the error type and response headers to decide whether to retry:
- Caller errors usually require changing the request, adding credit, or waiting for a usage limit to reset
- For temporary upstream or platform failures, retry with backoff
- If the response includes
Retry-After, wait at least that long before retrying
Once a streamed response has begun, the gateway cannot switch providers. The client decides whether to send a new request after a mid-stream failure.
Three cases behind no_available_provider
This type covers "the request did not land on any usable route", and the three cases call for very different handling — read the message, not just the code:
| The message says | What it means | What to do |
|---|---|---|
Use POST /v1/tasks instead (or another explicit instruction) | The model cannot be generated on this endpoint, but another endpoint can serve it | Follow the instruction; retrying this endpoint will not help |
temporarily unavailable while its upstream connections recover | Upstream connections are recovering | Back off and retry — this usually clears quickly |
This is on our side | It needs attention from us | Quote the request_id and contact us; when the message says retrying will not help, it will not |
Billing
- Failed failover attempts are not billed. If the request succeeds, only the successful result is charged
- If the client disconnects early, usage already incurred is still billed
- Failed image, video, and other media tasks are not billed
Error responses
The error body follows the calling protocol: OpenAI-compatible endpoints return an OpenAI shape, Anthropic Messages returns an Anthropic shape, and Gemini returns a Google RPC shape.
Caller errors retain the details needed to correct the request. Upstream and platform failures expose only a stable public message; raw provider responses are kept for server-side diagnostics. Every format includes a request_id.