> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fallback and Auto-Failover

> How Routor silently retries failed providers.

# Fallback and Auto-Failover

If one provider goes down, your app should not go down with it. Routor handles this automatically by trying the next model in the chain without your app ever seeing an error.

<img src="https://mintcdn.com/routor/cIATklos4kQp2x0I/images/fallback-hero.svg?fit=max&auto=format&n=cIATklos4kQp2x0I&q=85&s=1695db6fa8eaba80e449d98573dce396" alt="Auto-failover - Routor silently retries the next provider, your app gets a clean response" width="1000" height="300" data-path="images/fallback-hero.svg" />

***

## How It Works

Every routing decision comes with a fallback chain. It is an ordered list of models to try, from preferred to least preferred within the tier.

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant R as Routor
    participant P1 as Kimi K2.6 (primary)
    participant P2 as Gemini 3.5 Flash (fallback 1)
    participant P3 as DeepSeek V4 Flash (fallback 2)

    App->>R: POST /v1/chat/completions

    R->>P1: Forward request
    P1-->>R: 503 Service Unavailable

    Note over R: Auto-failover - silent to app

    R->>P2: Forward request
    P2-->>R: 200 OK + response

    R-->>App: Response\nX-Routor-Model: google/gemini-3.5-flash\nX-Routor-Fallback: true
```

Your app gets a successful response. If your Routor deployment has `DEBUG_ROUTING=1` set, the only sign something happened is the `X-Routor-Fallback: true` header - otherwise, check the dashboard's request logs, which record fallback activity regardless of that setting.

***

## What Triggers a Fallback

| Situation                              | What Routor does                      |
| -------------------------------------- | ------------------------------------- |
| Provider returns a 5xx error           | Tries next model in chain             |
| Request times out                      | Tries next model in chain             |
| Provider rate-limits the request (429) | Tries next model in chain             |
| Model context window too small         | Tries next model with a larger window |
| All models in the chain fail           | Returns 502 to your app               |

***

## Startup Validation

Before accepting any traffic, Routor pings every configured provider using their free `/models` endpoint. This costs nothing and takes a few seconds.

Any provider with an invalid key or an unreachable endpoint gets removed from the routing pool right there. They will not show up in any fallback chain until the server restarts with a working key.

So the fallback chain you get is always made of providers that are actually reachable right now.

***

## Detecting a Fallback

When Routor falls back to a secondary model, and the server has `DEBUG_ROUTING=1` set, it adds a header:

```
X-Routor-Fallback: true
```

You can monitor this in your logging when the header is available. Either way, fallback activity is visible in the dashboard's request logs - that's the reliable source if you're not running with the debug flag on.

***

## Checking Provider Status

The [Provider Health](dashboard/providers.md) page in the dashboard shows which providers are active, their error rates, and latency over the past 5 minutes.

***

## If Everything Fails

If every model in the fallback chain fails, Routor returns a `502`:

```json theme={null}
{
  "error": {
    "message": "All providers in the fallback chain failed. Please try again.",
    "type":    "provider_error",
    "code":    "all_models_failed"
  }
}
```

This is rare. It requires multiple providers to fail at the same time. In most real outages, at least one fallback model is available.