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
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:
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:
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.
When It Runs
Failover is attempted only after the primary request returns:
5xx429- model unavailable, unsupported, or not found style errors
- upstream failure messages relayed with a
4xx status (aggregator providers
such as OpenCode Zen can report a transient failure of their own upstream as
400 "Upstream request failed")
It currently applies to translated /v1/chat/completions, /v1/responses,
and /v1/messages requests, not /v1/embeddings.Last modified on August 1, 2026
