---
title: "Model fallbacks"
description: "With model fallbacks, pirouter switches a request to another model when the one you asked for is unavailable. This page covers how to name fallback models, when a switch happens, and how it is billed."
canonical: "https://pirouter.ai/docs/fallbacks"
last-updated: "2026-10-13"
lang: "en"
source: "content/docs/en/(start)/fallbacks.mdx"
---

# Model fallbacks

With model fallbacks, pirouter switches a request to another model when the one you asked for is unavailable. This page covers how to name fallback models, when a switch happens, and how it is billed.

[Provider routing](https://pirouter.ai/docs/routing.md) switches between the providers of one model. Model fallbacks go a step further: when no provider of a model can serve, pirouter moves the request to the next model you named.

## Name fallback models on a request

Add a `models` array to the request body. pirouter tries `model` first, then the array in order.

```bash
curl https://api.pirouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $PIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "models": ["anthropic/claude-haiku-5.5", "openai/gpt-6-sol"],
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'
```

- `models` holds at most 3 entries; more returns `422`.
- An entry equal to `model`, or repeated, is dropped.
- Without `model`, the first entry of `models` is the primary model.
- Requests on all three protocols accept `models`. On the Gemini protocol the primary model is in the path and `models` is only the fallback list.

Every fallback model is checked when the request arrives. If any of them does not exist, the whole request returns `404 model_not_found`, the `message` names it, and nothing has been forwarded.

The `route` field accepts only `"fallback"`, which behaves the same as leaving `route` out.

## Set fallback models for the workspace

Add them under **Fallback models** on the **Routing** page of the console: at most 3, and only chat text models. Only workspace owners can change them.

The workspace list applies only when the request has no `models` of its own. A request that sends `models` uses exactly that list; the workspace list is not appended.

A model on the workspace list that has gone offline is skipped without an error.

## When it switches

The request moves to the next model in two cases:

1. The current model has no provider that can serve: the [routing settings](https://pirouter.ai/docs/routing.md#when-no-provider-is-left) excluded them all, or they are all down.
2. A provider of the current model failed before the first byte, and that model has no other provider left to retry.

pirouter switches to the next model only before the response starts. Once the response has started, no later error changes the model.

A request is tried at most 5 times in total, across all its models.

`"allow_fallbacks": false` in `provider` limits providers, not `models`: on the next model the choice among its providers starts afresh.

## Billing

You pay only for the attempt that answered, at the price of its own model and provider. An attempt that failed and was taken over is not billed.

## Which model answered

The `model` in the response body is the ID of the model that answered. When it differs from the `model` you sent, a fallback happened. The `X-Pi-Model` response header holds the same value, and `X-Pi-Provider` names the provider that served it.

## Not available today

- **Presets.** A request that sends `preset` returns `422`.
- **A dedicated field saying a fallback happened.** Compare the response's `model` with the one you sent.

## Next steps

- [Provider routing](https://pirouter.ai/docs/routing.md): How a provider is chosen among those serving one model.
- [Models and protocols](https://pirouter.ai/docs/models.md): How model IDs are written and which protocols each model accepts.