Model Fallbacks

The models parameter lets you automatically try other models if the primary model’s providers are down, rate-limited, or refuse to reply due to content moderation.

How It Works

Provide an array of model IDs in priority order. If the first model returns an error, OpenRouter will automatically try the next model in the list.

1
import { OpenRouter } from '@openrouter/sdk';
2
3
const openRouter = new OpenRouter({
4
  apiKey: '<OPENROUTER_API_KEY>',
5
});
6
7
const completion = await openRouter.chat.send({
8
  models: ['~anthropic/claude-sonnet-latest', 'gryphe/mythomax-l2-13b'],
9
  messages: [
10
    {
11
      role: 'user',
12
      content: 'What is the meaning of life?',
13
    },
14
  ],
15
});
16
17
console.log(completion.choices[0].message.content);

Fallback Behavior

If the model you selected returns an error, OpenRouter will try to use the fallback model instead. If the fallback model is down or returns an error, OpenRouter will return that error.

By default, any error can trigger the use of a fallback model, including:

• Context length validation errors
• Moderation flags for filtered models
• Rate-limiting
• Downtime

Pricing

Requests are priced using the model that was ultimately used, which will be returned in the model attribute of the response body.

Using with the Anthropic Messages API

The Anthropic Messages API endpoint (/api/v1/messages) accepts the fallbacks parameter, matching the shape used by Anthropic’s SDKs. Each entry names a fallback model to try in order, and the list maps to OpenRouter’s models routing, so fallbacks trigger on the same errors listed above (rate limits, downtime, moderation refusals), not only on refusals.

1
import Anthropic from '@anthropic-ai/sdk';
2
3
const anthropic = new Anthropic({
4
  baseURL: 'https://openrouter.ai/api',
5
  apiKey: '<OPENROUTER_API_KEY>',
6
});
7
8
const message = await anthropic.beta.messages.create({
9
  model: 'anthropic/claude-sonnet-4.5',
10
  max_tokens: 1024,
11
  fallbacks: [{ model: 'anthropic/claude-opus-4.1' }],
12
  messages: [{ role: 'user', content: 'What is the meaning of life?' }],
13
});

Limitations

• Each fallbacks entry accepts only the model field. Per-attempt overrides such as max_tokens, thinking, speed, or output_config are rejected with a 400 error.
• fallbacks cannot be combined with the models parameter; sending both returns a 400 error.
• fallbacks accepts at most 3 entries; longer lists return a 400 error.

Using with OpenAI SDK

To use the models array with the OpenAI SDK, include it in the extra_body parameter. In the example below, ~openai/gpt-latest will be tried first, and the models array will be tried in order as fallbacks.

1
from openai import OpenAI
2
3
openai_client = OpenAI(
4
  base_url="https://openrouter.ai/api/v1",
5
  api_key={{API_KEY_REF}},
6
)
7
8
completion = openai_client.chat.completions.create(
9
    model="~openai/gpt-latest",
10
    extra_body={
11
        "models": ["~anthropic/claude-sonnet-latest", "gryphe/mythomax-l2-13b"],
12
    },
13
    messages=[
14
        {
15
            "role": "user",
16
            "content": "What is the meaning of life?"
17
        }
18
    ]
19
)
20
21
print(completion.choices[0].message.content)