# Model fallback

Model fallback tries up to five models in your order until one answers. It works on
`POST /v1/chat/completions` and `POST /v1/messages`, streamed or not.

## Request

Send `models` next to `model`:

```bash
curl https://demo-api.routerplus.com/v1/chat/completions \
  -H "Authorization: Bearer $TM_API_KEY" -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "models": ["gpt-6-luna", "z-ai/glm-5.3"],
    "messages": [{ "role": "user", "content": "Hello" }]
  }'
```

| Field | Rule |
|---|---|
| `models` | An array of 1 to 5 model ids. |
| `model` | Tried first. Without `model`, the first entry of `models` goes first. |
| `route` | Optional. The only value is `"fallback"`. |

- The gateway removes duplicates and keeps your order.
- Each model gets your request with its own id in `model`. All other fields go as you sent them.
- Each model first fails over between its own providers (see
  [Routing & failover](/docs/routing)). The gateway tries the next model only after every
  provider of the current model failed.

## When the next model is tried

The gateway moves to the next model only before any part of an answer reaches you.

| Response from a model | What happens |
|---|---|
| 2xx | You get this answer. The request stays with this model. |
| 429, 404, 5xx, other 4xx | The gateway tries the next model. |
| 400 because the model cannot take the request | The gateway tries the next model. This covers context length, a model that is not available, an unsupported parameter, an input type (for example images) and `response_format`. |
| Any other 400 | You get this error. The request itself is wrong, so another model would fail the same way. |
| 401, 403 | You get this error at once. This covers a bad key and a guardrail refusal. |
| 413 | You get this error at once. The request is too large for every model. |

When every model fails, you get the last model's error unchanged.

The gateway does not switch models after a stream starts. A failure in the stream ends it with
the error chunk in [Streaming](/docs/streaming).

## Response

The response is the answering model's own answer, and `model` names that model. The usual
headers (`x-request-id`, `x-tm-provider`, `x-tm-attempts` and the others) come from that
model's call. The gateway adds two headers:

| Header | Meaning |
|---|---|
| `x-tm-fallback-model` | The model that answered. |
| `x-tm-fallback-tried` | How many models were tried, the answering model included. Also set on an error. |

## Billing

RouterPlus bills each model call as a direct call to that model. A model that failed before it
produced output costs what its provider billed for the attempt, as in
[Routing & failover](/docs/routing#the-commit-boundary).

## Errors

| Status | Cause |
|---|---|
| 400 `invalid_request` | `models` is not an array of 1 to 5 non-empty strings, or `route` is not `"fallback"`. |