Original explainer
OpenRouter model fallbacks: write a models list and check which model answered
Set an order with the models array, learn which errors trigger fallback, and check the model that answered and the billing basis in the response.
When the primary model is rate-limited, down or refuses, a caller usually wants to retry with another model, but a different model also changes the output and the billing. This guide writes a request with fallbacks and gives the caller a checklist. You need an OpenRouter API key and must have confirmed that each candidate model suits your data and task. The request body is written from the official fallback page and checked offline; no request was sent, no account was used and no credit was spent.
Action and acceptance sequence
Set the order
List candidate models by priority and note what input each can accept.[1]
Write the request
Use the models array in the body; the Anthropic Messages endpoint uses fallbacks instead.[1]
Check the result
Read the model in the response and record whether a fallback happened.[1]
Decide when a model swap is acceptable
The official page says that by default any error can trigger a fallback, including context length validation errors, moderation flags, rate limiting and downtime. A fallback is therefore more than a backup for outages; an overly long input can also move to another model. Before writing anything, make a table: can each candidate accept the same input, does its output format still satisfy downstream steps, and may it process your data? If any answer is unknown, leave that model out of the list (this is a suggestion of this guide, not an official requirement).[1]
Write the models array
The official example sends a POST to https://openrouter.ai/api/v1/responses with models holding model IDs in priority order, plus input. The original exercise body has two fields: models takes the page example values ~anthropic/claude-sonnet-latest and gryphe/mythomax-l2-13b, and input is one synthetic request to summarize a meeting note. Whether those IDs are currently available was not checked; replace them with models you have confirmed. The next model is tried only when the first returns an error, and if the fallback also errors, that error is what comes back.[1]
Billing and the fallbacks limits
Per the official page, a request is billed at the model that was ultimately used, and that model is named in the model field of the response body. If a :free model is followed by a paid model and a fallback occurs, the paid model price applies; to stay free, list only :free models. On the Anthropic Messages endpoint /api/v1/messages, use the fallbacks parameter instead: at most 3 entries, each with only a model field, and it cannot be combined with models; violations return 400. This guide quotes no price figures; check prices on the official pages yourself.[1]
Checks and stop conditions
The offline script flags these cases: models and fallbacks together, more than 3 fallbacks, an entry carrying overrides such as max_tokens, a models list with a single entry, and a paid model mixed into a list that must stay free. When the first list entry is a concrete model ID, a response whose model differs from it can be recorded as a fallback. If the first entry is a ~ alias such as ~anthropic/claude-sonnet-latest in this exercise, the model in the response is likely a resolved concrete ID and this comparison would misfire; confirm the returned model value from one real response first, which this guide did not verify. The request body passed jq validation, and the curl script was only syntax-checked with bash -n, not executed; it contains no key. The caller should record the actual model of every response. If the fallback share rises unexpectedly or the final result is an error, stop increasing traffic and investigate the primary model errors first. Fallback speed and output quality were not verified.[1]
Article sources
Original editorial content; official descriptions and checking suggestions are distinguished.
Tools in this explainer
Tool directory
OpenRouter
Access multiple AI models through one API, with a model directory, routing, and developer integrations.