Model fallback
Try a list of models in order.
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:
curl https://dev2-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). 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.
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.
Errors
| Status | Cause |
|---|---|
400 invalid_request | models is not an array of 1 to 5 non-empty strings, or route is not "fallback". |
For agents: /docs/model-fallback.md and /llms.txt