Model Fallback

Model Fallback ensures high availability by automatically retrying requests on alternative models when the primary model is temporarily unavailable due to timeouts, provider outages, rate limits, etc.

Fallback is not triggered for provider validation errors (e.g., invalid, unsupported, or malformed request parameters). These errors are returned immediately without retrying other models.

How It Works

Each model can have a fallback model configured.

When a request fails on the primary model:

1. The router tries the fallback model automatically

2. If that model also fails, the router continues down the fallback chain

3. The process stops as soon as a model succeeds

Fallback models can themselves have fallbacks, forming a chained retry sequence.

Example Fallback Chain

devstral-2512 → devstral-small-2512 → devstral-small-2507
    (fails)          (fails)            (succeeds ✅)              

If all models in the fallback chain fail, you receive the error details of the first attempted model.

You only pay for the successful request and for the model that ultimately served the response.

Via Web Console

1. Go to your Project Settings → Inference Section.

2. Toggle Model Fallback ON ✅ to automatically retry failed requests using fallback models.

1. Toggle OFF ❌ to disable fallback behavior. Requests will fail immediately if the primary model is unavailable.

Via API

You can control this behavior directly in your requests using the enable_model_fallback parameter:

{
  "model": "devstral-2512",
  "messages": [...],
  "enable_model_fallback": true
}

• true ✅ (default) → Fallback models are allowed

• false ❌ → Only the originally requested model is used

Fallback Model Selection Logic

Fallback models are selected within the same model family and capability tier to maintain compatibility and predictable behavior.

• Version Downgrade: Newer versions fall back to older versions

gpt-5.1 → gpt-5 → gpt-4.1 → gpt-4o → gpt-4o-mini

• Size Downgrade: Larger models fall back to smaller variants

gpt-oss-120b → gpt-oss-20b

• Embedding Models: Embedding models fall back only within the same embedding family to preserve vector space compatibility.

Here's the updated documentation page with the Custom Fallback Chains section added. Since the visualizer isn't available, here's the fully marked-up content you can paste into your docs system:

Custom Fallback Chains

By default, fallback models are selected automatically as descirbed above. You can override this behavior by specifying your own ordered list of fallback models using the fallbacks request parameter.

When fallbacks is provided, it replaces the default fallback mechanism entirely. The router will only attempt the models listed in the array, in order.

Request Parameter

Parameter	Type	Description
fallbacks	string[]	An ordered list of model IDs to try if the primary model fails. Overrides the default fallback chain. Models are attempted left to right until one succeeds.

Example

{
  "model": "claude-opus4-8",
  "messages": [...],
  "fallbacks": ["claude-opus4-7", "claude-opus4-6"]
}

In this example, the router attempts models in this order:

claude-opus4-8 → claude-opus4-7 → claude-opus4-6
 (primary)        (fallback 1)     (fallback 2)

Behavior

• Ordered retry: Models in fallbacks are tried left to right; the router stops as soon as one succeeds.

• Overrides defaults: Providing fallbacks disables automatic family-based fallback selection entirely for that request.

• Cross-family support: Unlike default fallbacks, custom chains can span different model families.

• Cost: You are only billed for the model that successfully served the response.