Routing
Failover
When DigitSpace moves a request to the next provider, how many it tries, what your code sees, and when it stops and returns the error.
Each request gets a short list of offers, ranked by the routing strategy: three by default. They're tried in order, once each, until one answers.
What moves a request to the next provider
| The provider | What the gateway does |
|---|---|
| Times out (2 minutes) or can't be reached | Tries the next offer. |
Returns 429 (rate limited) | Tries the next offer. |
Returns a 5xx error | Tries the next offer. |
Returns another 4xx error, such as a bad request | Stops and returns the provider's status with its message: "The provider rejected the request: …". Another provider would most likely reject it too. |
If every offer fails, you get 502 provider_failed: "Every provider for this model failed. Try again shortly."
Your code sees one normal response from whichever provider answered. The dashboard's Activity page tags retried requests, and each request's detail shows the provider that served it and the others that were considered.
Health
The gateway keeps the last 50 results of each provider and model. After three failures in a row, that offer is paused and routing skips it. A provider's client errors (other 4xx) don't count against its health.
What failover can't do
- Move a stream that has started. Failover happens before the first byte. See Streaming.
- Leave a pinned provider. With
provider/model, only that provider's offers are tried. - Retry your request after the gateway answers. If you get
502or503, retrying later is up to your code. Wait a few seconds first.
Mixing your keys and credits
With Own keys, then credits, each offer on the list uses your key if you have one for its provider, otherwise credits. So a request can fail over from a provider on your key to another provider on credits. See Credits or your own keys.
Checked against the gateway on 31 October 2026. Something wrong or missing? Tell us.