---
title: "Model fallbacks"
description: "Backup model lists, their limits and which model is billed."
canonical_url: "https://minirouter.sh/docs/model-fallbacks"
markdown_url: "https://minirouter.sh/docs/model-fallbacks.md"
last_updated: "2026-09-26"
---

# Model fallbacks

List up to three models. If one cannot start a response, the next one answers.

## Send a fallback list

Chat Completions and Responses take `models`. Messages takes `fallbacks`.

```sh
curl https://api.minirouter.sh/v1/chat/completions \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-6-sol",
  "models": [
    "google/gemini-3.8-flash",
    "openai/gpt-6-luna"
  ],
  "messages": [
    {
      "role": "user",
      "content": "Explain an API gateway in one sentence."
    }
  ],
  "max_tokens": 256
}'
```

```sh
curl https://api.minirouter.sh/v1/messages \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
  "model": "openai/gpt-6-sol",
  "fallbacks": [
    {
      "model": "google/gemini-3.8-flash"
    },
    {
      "model": "openai/gpt-6-luna"
    }
  ],
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Explain an API gateway in one sentence."
    }
  ]
}'
```

Examples read your key from `MINIROUTER_KEY`.

## How it works

1. **First choice**: `model` tries first.
2. **Next in line**: If it cannot start, the next model answers.
3. **Locked in**: Once output starts, the model stays. See [Failover](https://minirouter.sh/docs/failover).

## Rules

| Rule | Detail |
| --- | --- |
| Length | Three distinct models, including `model`. |
| Order | `model`, then the list. Without `model`, the first entry leads. |
| Eligibility | In the catalog, allowed on your key and served by a [permitted provider](https://minirouter.sh/docs/provider-selection). |
| Not with | `minirouter/auto`, Auto Free or `providerOptions`. |

## Billing

- **Charge**: The model that answered.
- **Hold**: Covers the priciest model until the request settles.
- **Answering model**: Named in `model` and `x-minirouter-model`. On a stream, read `model` from the chunks.

## Settings and errors

| Case | Result |
| --- | --- |
| Prevent overrides | [Routing settings](https://minirouter.sh/dashboard/routing) can ignore `models` and `fallbacks`. Those responses carry `x-minirouter-overrides: ignored`. |
| 400 `invalid_request` | Too many models, a repeat, an unknown or disallowed model, or no provider serves them all. |