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

# Failover

> Configure GoModel failover with manual mappings and know when failover attempts run.

<img src="https://mintcdn.com/gomodel/F9WyPCuHD-_clZPr/features/failover.png?fit=max&auto=format&n=F9WyPCuHD-_clZPr&q=85&s=d349cfb5da6395ed30334b30d2420398" alt="GoModel dashboard failover mapping editor for a model, showing an ordered fallback model list, Add fallback model and Generate automatically buttons" style={{ width: "100%", maxWidth: "795px", height: "auto" }} className="rounded-lg" width="2922" height="1812" data-path="features/failover.png" />

## Overview

GoModel exposes failover through the `failover` config block, environment
variables, and the Dashboard.

When a request fails, GoModel can retry it against alternate models. Runtime
failover uses manual rules only.

## Manual Mappings

```yaml theme={null}
failover:
  enabled: true
  manual_rules_path: "config/failover.json"
```

`config/failover.json` is a JSON object where each primary model entry contains
an ordered failover target list (array); top-level keys are not ordered:

```json theme={null}
{
  "gpt-4o": [
    "azure/gpt-4o",
    "gemini/gemini-2.5-pro"
  ]
}
```

The order-sensitive part is the array under each model entry.

GoModel tries the listed candidates in order and stops on the first success.
Use bare model names like `gpt-4o` or provider-qualified selectors like
`azure/gpt-4o`.

For env-only deployments, use inline JSON:

```bash theme={null}
FAILOVER_RULES_JSON='{"gpt-4o":["azure/gpt-4o","gemini/gemini-2.5-pro"]}'
```

`failover.default_mode` and `FAILOVER_MODE` are deprecated
compatibility inputs. They are accepted but ignored by runtime failover.

The Dashboard can generate suggested mappings from model metadata, but
suggestions must be saved as manual mappings before they affect traffic.

Two ways to reach the generator in the dashboard:

* Per model: open a model's row on the **Models** page and click the
  shuffle icon to edit its failover mapping, then **Generate automatically**
  to populate suggested fallback models before **Save**.
* For everything at once: **Settings -> Failover -> Generate failover models
  automatically** proposes mappings for every eligible model in one pass.

<img src="https://mintcdn.com/gomodel/8KxjSi0DgR_rxTeY/features/failover-generate.png?fit=max&auto=format&n=8KxjSi0DgR_rxTeY&q=85&s=f301548c3f0329747500580e578b337a" alt="GoModel dashboard Settings page Failover section with Generate failover models automatically and Remove all the failover models buttons" style={{ width: "100%", maxWidth: "1000px", height: "auto" }} className="rounded-lg" width="2880" height="350" data-path="features/failover-generate.png" />

## When It Runs

Failover is attempted only after the primary request returns:

* `5xx`
* `429`
* model unavailable, unsupported, or not found style errors

It currently applies to translated `/v1/chat/completions`, `/v1/responses`,
and `/v1/messages` requests, not `/v1/embeddings`.