Skip to main content

​
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

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: 
{
  "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: 
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.