> For the complete documentation index, see [llms.txt](https://docs.cortecs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortecs.ai/routing/model-fallback.md).

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

{% hint style="info" %}
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.
{% endhint %}

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

```json
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.**

{% hint style="success" %}
**You only pay for the successful request and for the model that ultimately served the response.**
{% endhint %}

#### Via Web Console

1. Go to your [**Project Settings**](https://cortecs.ai/userArea/userProfile) **→ Inference Section**.
2. Toggle **Model Fallback ON** ✅ to automatically retry failed requests using fallback models.

<figure><img src="/files/fKUpXjiNTU6EN4jqvJGJ" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/fJnuy4q0BpznC5wXyMpl" alt=""><figcaption></figcaption></figure>

#### Via API

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

```json
{
  "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

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

* **Size Downgrade:** Larger models fall back to smaller variants

<pre class="language-json"><code class="lang-json"><strong>gpt-oss-120b → gpt-oss-20b
</strong></code></pre>

* **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&#x20;

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.

{% hint style="info" %}
When `fallbacks` is provided, it **replaces** the default fallback mechanism entirely. The router will only attempt the models listed in the array, in order.
{% endhint %}

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

```json
{
  "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.