# 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.

Source: https://digitspace.ai/docs/routing/failover · Last checked: 2026-10-31

Each request gets a short list of offers, ranked by the [routing strategy](/docs/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](/docs/dashboard/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](/docs/api/streaming#when-a-provider-fails).
- **Leave a pinned provider.** With `provider/model`, only that provider's offers are tried.
- **Retry your request after the gateway answers.** If you get `502` or `503`, 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](/docs/concepts#credits-or-your-own-keys).