Combos & fallback

Put several models behind one name. kRouter falls back from one to the next, rotates them, or asks a panel of models and merges the answers.

A combo is a named list of provider/model IDs that you call as if it were one model. With the default strategy, kRouter sends the request to one model; if that fails with an error another model might not have, it tries the next. Your tool sees an error only when every entry has failed, or when the error is one that every model would give.

A typical combo

Combo: "always-on"
  1. cc/claude-opus-4-7        subscription you already pay for
  2. glm/glm-5.1               cheap API key
  3. kr/claude-sonnet-4.5      free (Kiro)

Requests go to Claude Code while it works.
When that account is rate limited or out of quota, kRouter cools it down and tries your other Claude Code accounts, if you have any, then GLM.
If GLM fails as well, Kiro answers.
When the Claude Code cooldown ends, that account is back in play.

The list is a preference, not a fixed order. Before each request kRouter adjusts it:

Input type: if the request contains an image (or a PDF, audio or video), the entries that can read it move ahead of the ones that cannot. Since v0.5.166 that is a hard split rather than one more sort, so nothing below can cross it.
Remaining quota: within each of those two groups, entries whose provider reports remaining quota for that specific model go first, the one with the most left leading. Providers that report quota per time window instead of per model (a 5-hour or weekly window, for example) give no per-model figure, so their entries stay in the order you gave them, after the ones that do. Until v0.5.166 this sort ran across the whole list and could lift a text-only entry above the one that could read your image, which then got stripped.

Creating a combo

In the dashboard:

Open Combos
Click Create Combo
Give it a name (always-on, cheap-coding, free-only)
Add models, your preferred one first
Save

Then use the name as the model:

Base URL: http://localhost:20128/v1
Model:    always-on

Combos are listed by GET /v1/models, so tools that show a model list will offer them.

When kRouter moves on

A failing model first gets a cooldown on the account that failed, and kRouter tries the provider's other accounts. When none is left, the combo moves to its next entry.

The rows are listed in the order kRouter checks them: the first that matches decides.

What happened	What kRouter does
GitHub Copilot's monthly premium requests used up	The whole account is held until the 1st of next month (UTC)
Anthropic's monthly spend cap, or a spend limit you set yourself	The whole account is held until the date the message names, or 00:00 UTC on the 1st of next month if it names none (v0.5.164). A successful Test connection clears it early
OpenRouter's free-model daily cap	That model is parked on that account until the reset OpenRouter names, or 00:00 UTC (v0.5.164). Paid models on the same key keep working
The provider names an exact reset time	That model is parked on that account until the reset, 6 hours at most. Since v0.5.166 this also outranks the 90-second reading further down
Codex refuses a model the account's ChatGPT plan cannot use	A 30-minute cooldown on that model, and the next account is tried (v0.5.166). Any other Codex 400 is request-scoped, like the 4xx row below
kRouter's own 503 when no concurrency slot on the account is free	A 2-second cooldown on that model, doubling if it keeps happening (v0.5.166)
"Verify your account", account suspended or deactivated	The whole account is locked for 24 hours, longer if it keeps happening -- and it stays out of rotation after that until a Test connection succeeds
A 400 that is about the credential, not the request -- an empty Anthropic credit balance, an invalid Gemini key, a region block	2-minute cooldown on that model, and the next account is tried
Kiro's monthly limit	The whole account is locked for about 30 days
The model no longer exists upstream	A 30-minute cooldown on that model; the combo first tries up to 3 related models from the same family, then the next entry
Prompt too long, request too large	Returned to you at once, with no cooldown: every model would reject it
Rate limit or overload (429, "rate limit", "too many requests", "quota exceeded", "overloaded")	Cooldown on that model with exponential backoff, from 2 seconds up to 5 minutes
...except when that 429 brought no reset time and the cached quota for that model still looks healthy	Read as the per-minute window instead: a 90-second cooldown on that model
401, 402, 403 or 404 with no more specific match	2-minute cooldown on that model
Any other 4xx: a malformed body, an unsupported parameter, a failed validation	No cooldown, and no other account is tried -- the request is the problem, not the credential. The combo still advances to its next entry, which is a different model and may accept it (v0.5.166)
Any other error, including 500, 502, 503 and 504	30-second cooldown, then the next account or entry

One case is not an error at all: an entry that answers 200 with nothing usable -- no text, no tool call, no reasoning and no real finish reason -- falls through to the next entry since v0.5.166. The last entry's answer is always returned as it came.

On a 502, 503 or 504 whose cooldown is 5 seconds or less, the combo waits that cooldown out before moving on, so a provider that is briefly busy gets a chance rather than being skipped instantly.

When every account of every entry is parked, your tool gets a 503 carrying the earliest Retry-After among them. Before v0.5.166 a combo lost that header, because it read the wait only from the response body, and the "all accounts parked" reply puts it only in the header.

Cooldowns and locks are stored in kRouter's database, so a restart does not put a blocked account straight back into rotation. The errors reference explains individual errors.

Strategies

Each combo uses one of three strategies, chosen on its card on the Combos page. Combos you leave alone follow the global setting under Settings (fallback, or a round-robin toggle with its sticky limit).

Fallback (default): try the entries as described above.
Round-robin: rotate which entry goes first. By default it moves on after every request; the sticky limit sets how many requests each model gets before rotating. Failures still fall through to the next entry.
Fusion: send the request to several of the combo's models at once, then have a judge model write one answer from their replies. It waits for at least 2 answers, gives late ones 8 more seconds, and stops at 90 seconds.

These strategies choose a model. Which account serves that model is a separate setting; see The Zenith Routing Engine.

Entries from the same provider

Entries can share a provider:

Combo: "claude-first"
  1. cc/claude-opus-4-7        deep work
  2. cc/claude-sonnet-4-6      same accounts, lighter model
  3. glm/glm-5.1               cheap backup

Combos inside combos

An entry can be another combo's name:

Combo: "free-only"
  1. kr/claude-sonnet-4.5
  2. mmf/mimo-auto
 
Combo: "premium-with-free-backup"
  1. cc/claude-opus-4-7
  2. glm/glm-5.1
  3. free-only                ← used when both above fail

Nesting stops at 3 levels. A deeper chain, or a cycle, returns a 400 error that names the combo, instead of looping.

When to use a combo

A single model: quick experiments, where an error now and then is fine
Subscription plus one cheap backup: the simplest setup that keeps working when the subscription runs out (for example when Claude Code hits its weekly limit)
Three tiers: long agent runs you do not want interrupted
Free only: no cost, within each free service's limits

Where to go next

Core concepts: token savers, MITM and quota tracking
Providers: how each kind of provider connects
API reference: the endpoints kRouter serves