> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aireserve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fallback models

> List the models you are willing to be served by, in order, and the gateway tries the next one when the one before it fails.

Name the models you accept, in order of preference, on the request itself. If
the first one fails, the gateway retries the same request on the next one, so
a provider incident on one model does not take your feature down. No portal
configuration is needed.

```json theme={"dark"}
{
  "models": ["claude-fable-5-1", "gpt-6-astra", "kimi-k3-fireworks"],
  "messages": [{ "role": "user", "content": "Summarize this quarter's board update." }]
}
```

`models` is shorthand. The first entry is the primary `model`; the rest become
`fallbacks`. The two spellings below are identical:

```json theme={"dark"}
{ "models": ["claude-fable-5-1", "gpt-6-astra"] }
```

```json theme={"dark"}
{ "model": "claude-fable-5-1", "fallbacks": ["gpt-6-astra"] }
```

Keep `model` a single string. Official OpenAI SDKs type it that way, and every
coding tool that replays `model` verbatim depends on it. List up to four models:
one primary plus three fallbacks.

```bash curl theme={"dark"}
curl https://api.aireserve.com/v1/chat/completions \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["claude-fable-5-1", "gpt-6-astra", "kimi-k3-fireworks"],
    "messages": [{ "role": "user", "content": "hello" }]
  }'
```

```python Python theme={"dark"}
from openai import OpenAI

client = OpenAI(base_url="https://api.aireserve.com/v1", api_key=os.environ["AIRESERVE_API_KEY"])

res = client.chat.completions.with_raw_response.create(
    model="claude-fable-5-1",
    messages=[{"role": "user", "content": "hello"}],
    extra_body={"fallbacks": ["gpt-6-astra", "kimi-k3-fireworks"]},
)
served = res.headers.get("x-aireserve-served-model")  # set only when a fallback answered
print(res.parse().choices[0].message.content, served)
```

```typescript TypeScript theme={"dark"}
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.aireserve.com/v1", apiKey: process.env.AIRESERVE_API_KEY });

const params = {
  model: "claude-fable-5-1",
  messages: [{ role: "user", content: "hello" }],
  fallbacks: ["gpt-6-astra", "kimi-k3-fireworks"], // gateway extension, forwarded as-is
} as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming;

const { data, response } = await client.chat.completions.create(params).withResponse();

const served = response.headers.get("x-aireserve-served-model"); // null unless a fallback answered
console.log(data.choices[0].message.content, served);
```

## Which model answered

When a fallback served the request, the response carries the
`x-aireserve-served-model` header naming it. Read the header, not the body's
`model` field. The header is absent when the primary answered. Your usage
ledger records both the requested and the served model on every row, so
reporting and billing follow what actually ran.

## How entries are checked

Every entry is held to the same policy as the primary model. An entry is
dropped from the chain, never served silently, when it is:

* not a model in the [catalog](/models) (after alias resolution, so `fable-5-1`
  and `claude-fable-5-1` are both fine);
* outside your organization's model allowlist or inside its blocklist;
* behind an [organization consent](/models#organization-consent-gates) your
  organization has not accepted (China-hosted serving, training use, and so
  on), or behind a restricted-access list you are not on;
* the primary itself, or a duplicate of an earlier entry.

If nothing survives, the request runs exactly as if you had sent no list.

## Portal defaults and the request-level list

Organization admins can configure a default fallback chain per model in the
portal under Inference → Router. A request-level list replaces that default
for the one request that carries it.

Fallbacks are opt-in per organization or per request. A new organization has
no failover of any kind, so a provider's real error reaches you. Configuring
at least one fallback chain in the portal switches failover on for the whole
organization: the chains you wrote apply to the models they name, and the
models we have paired across providers with identical weights (the Claude
models on Anthropic and Amazon Bedrock, for example) fail over to their
sibling provider automatically, same model, same request, with nothing to
configure per model. To keep a chained model on the same weights first,
list the sibling as its first rung (`claude-sonnet-4-6-bedrock`, then a
different model). Ask support to change either behaviour. Two edge cases:

* `"fallbacks": []` opts a single request out of the organization's default
  chain. `models` never produces an empty list, so it cannot opt out by
  accident.
* Requests on your organization's own provider key ([BYOK](/capabilities/byok))
  never fall back to a different provider.

## Where it applies

| Endpoint | `models` / `fallbacks` |
| - | - |
| `POST /v1/chat/completions` | Supported |
| `POST /v1/responses` | Supported |
| `POST /v1/messages` | Not a failover chain. On the Anthropic wire, `fallbacks` is Anthropic's own `[{ "model": "…" }]` list consulted only when the primary refuses on a safety classifier. Error failover there uses the organization's portal chain. |

Failover engages on upstream failures (provider errors, rate limits, timeouts,
connection errors) after the gateway's own retries on the primary are
exhausted. The same request, unchanged, is then sent to the next model in your
list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.