Skip to main content
kRouter

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), models that can read it move to the front.
  • Remaining quota: 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.

Creating a combo

In the dashboard:

  1. Open Combos
  2. Click Create Combo
  3. Give it a name (always-on, cheap-coding, free-only)
  4. Add models, your preferred one first
  5. 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.

What happenedWhat kRouter does
Rate limit or overload (429, "rate limit", "too many requests", "quota exceeded", "overloaded")Cooldown with exponential backoff, from 2 seconds up to 5 minutes
A 429 while quota data says the account still has plentyTreated as a per-minute limit: 90-second cooldown
The provider names an exact reset timeThat model is parked on that account until the reset, 6 hours at most
Monthly limit reachedKiro: the whole account is locked for about 30 days. GitHub Copilot's monthly premium-request limit: the whole account is locked until the 1st of next month (UTC)
401, 402, 403 or 404 with no more specific match2-minute cooldown
Any other error, including 500, 502, 503 and 50430-second cooldown, then the next account or entry
The model no longer exists upstreamTries up to 3 related models from the same family, then the next entry
"Verify your account", account suspended or deactivatedThe whole account is locked for 24 hours, longer if it keeps happening
Prompt too long, request too largeReturned to you at once, with no cooldown: every model would reject it

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