> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel-feature-failover-management.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Failover

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

## Overview

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

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

## Manual Mappings

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

`config/fallback.json` is a JSON object where each primary model entry contains
an ordered fallback model 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"]}'
```

`fallback.default_mode` and `FEATURE_FALLBACK_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.

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