Skip to main content

​
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. Auto-failover - Routor silently retries the next provider, your app gets a clean response

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

SituationWhat Routor does
Provider returns a 5xx errorTries next model in chain
Request times outTries next model in chain
Provider rate-limits the request (429)Tries next model in chain
Model context window too smallTries next model with a larger window
All models in the chain failReturns 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 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: 
{
  "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.