Handle a model quota wall

A coding model has a ceiling: a subscription window, a monthly API quota, a credit balance, a premium-request allowance. When a task’s pinned model hits that ceiling, the run fails through no fault of the work.

SupaCloud handles that in two steps, and the split between them is the whole point:

• Same class → automatic. The task continues on an equivalent model of the same class (for example another flagship model, possibly from a different provider). No one has to do anything.
• Different class → your decision. If every model of that class is out too, SupaCloud does not quietly continue on something weaker. It parks the task on an approval gate and asks you.

Caution

A class change is never automatic and never expires into one. An unanswered tier-change gate waits indefinitely; the task stays blocked rather than being silently degraded.

The model classes

Class	What it is
flagship	Top-end reasoning models.
balanced	The everyday workhorse class.
fast	Cheap, low-latency models.
independent_review	A deliberately different-provider reviewer. It is a role, not a strength rung, so it has no weaker class to drop to.

Each class holds an ordered, provider-spanning chain of models. On a quota wall SupaCloud walks that chain in order and takes the first model that is genuinely usable right now — meaning your workspace has a credential for its provider, that credential still has quota headroom, and the provider’s circuit breaker is closed.

What you see when it happens

1. A line in the live feed. “Quota reached on claude-fable-5 — continuing on gpt-5.6-sol (same flagship class)”. The same line reaches your linked Telegram or Discord chat while you are following the task.

2. An audit entry. Every decision — a switch, a gate, an exhausted class, a spent cap — is recorded under Reports → Audit with the models involved.

3. A routing note. For a backlog-dispatched task the switch is also written to the routing decision log on the operations view.

When it asks you

The approval appears in your normal Approvals inbox (web, approvals in the web terminal, /approvals in Telegram or Discord) as a model class change gate:

Model class ‘flagship’ is exhausted (claude-fable-5 hit its quota and every equivalent model of that class is out of quota or unavailable). Fall back to the weaker ‘balanced’ class for this task? Rejecting leaves the task blocked on its own class.

• Approve — the task relaunches on the first usable model of the weaker class, within about a minute.
• Reject — the task stays where it is. Nothing is downgraded.

Note

A coordinator agent cannot answer this gate for you. Agents may answer only open-question gates; a class change is deliberately in a class they cannot decide.

Tip

To decide between the two, you usually want to know when the wall comes down. Open Reports → Usage: the exhausted window’s row carries its own reset countdown, so rejecting and waiting is a decision you can price. A rolling 5-hour window that filled at 14:00 is free again at 19:00 — the countdown states that rather than leaving you to guess, and the card tells you how fresh the reading is.

Limits that stop a runaway

• At most two automatic same-class switches per task. After that the same approval gate appears instead of a third switch.
• No ping-pong. A model the task has already run on is never offered again.
• One decision per run. A crash-recovered run cannot switch the same task twice.
• Unknown model → no guess. If the pinned model is not listed in any class chain, SupaCloud makes no assumption about its class and does not fall back; the task fails as it would have before. Add the model to your workspace chain to enable the fallback.

Change the chains for your workspace

The built-in chains are a sensible default, not a policy. A workspace owner or admin can replace any class’s chain — for example to prefer your own provider order, or to add a model the default does not know.

In the app

1. Open Settings → Models and scroll to Model fallback chains. The card shows the chains this workspace actually resolves right now — your override where you set one, the built-in chain everywhere else.

2. Expand a class (Flagship, Balanced, Fast, Independent second opinion — the independent_review class in the table above) to see its ordered candidates. Order is preference order: the first usable entry wins.

3. Per row, pick the harness, type the provider-native model id and optionally pin an effort (leave it on Keep the task’s effort to inherit the task’s own setting). Use the arrows to reorder and ✕ to remove.

4. Save. Only the classes you actually touched are written — a class you did not open keeps whatever it resolves today, including future built-in updates. Reset to built-in clears the whole workspace override in one step.

A member sees the same card read-only.

Note

Removing every row of a class and saving is meaningful: it switches the automatic fallback off for that class, so a quota wall there goes straight to the approval gate.

Through the API

The same override is one PATCH /api/workspaces/{id}/settings field:

{
  "model_fallback_chains": {
    "flagship": [
      { "agent": "codex", "model": "gpt-5.6-sol" },
      { "agent": "claude", "model": "claude-fable-5" }
    ]
  }
}

A class you do not name keeps its built-in chain; an empty array switches the automatic fallback off for that class; "model_fallback_chains": null clears the override entirely. Malformed input is rejected with a 400 — nothing is half-saved. The read side of the same endpoint returns both your raw override (model_fallback_chains) and the resolved result the runtime uses (model_fallback_chains_effective).

A narrower override: one agent profile

An agent profile can carry its own chains under retry_policy.model_fallback.chains (same shape), layered on top of the workspace chains for tasks that run on that profile. Edit it in Settings → Agent profiles → Raw.

Related

• Approve agent actions
• Track usage and budget
• Set the autonomy level

Let the evidence propose the order

Deciding the order by hand means keeping a benchmark board, a price list and your own run history in your head at once. SupaCloud can do that reading for you and propose an order — as a proposal, never as a change.

Ask for a proposal

1. In Settings → Models → Model fallback chains, use Calibrate from evidence. SupaCloud reads the model catalog (prices, lifecycle), the public benchmark boards and this workspace’s own run telemetry, and computes a proposed order. The external sources are not called live: a background refresh fetches them a few times a day into a snapshot, and the preview shows each snapshot’s age. Refresh now (admins, rate-limited) fetches on demand — a new ranking still needs a new calibrate run afterwards.

2. The preview plays the reordering: the list opens in your current order and settles into the proposed one, so you can see what moves rather than compare two lists. Use Play again to watch it once more.

3. Every movement states its reason and the numbers behind it, each with its source and the date of that measurement — not the date of the run. A movement that claims a measurement and cites none is marked on its own row and counted in the header; treat those as the lines to read hardest.

4. Apply to the chains writes the proposal. Discard records that you said no and changes nothing.

Note

Reopening the preview shows the run you already read, never a fresh one. Recomputing on open would mean deciding about a diff you had not seen.

Caution

If you edit the chains by hand between asking for a proposal and applying it, applying is refused and the chains stay as you left them — the proposal argues about a state that no longer exists. Ask for a fresh one.

When the evidence is not enough to rank

A price alone does not order models. When a run finds no quality and no speed measurement at all — every benchmark source down or unconfigured, no usable telemetry — the preview says so instead of proposing a price-sorted list: the current chains stay as they are, and only models that are unreachable, non-compliant, unable to call tools or vendor-retired are removed. Repair the sources named in the preview, refresh, and calibrate again. A movement that is carried only by its price is labelled price-backed only on its row.

Some figures stay inside your instance

A number carrying an instance only marker comes from a source whose licence permits internal use but not redistribution. You may read it; do not paste it outside your instance.

Letting it apply itself

A workspace at autonomy Autonomous or above lets a daily pass apply a proposal without asking — but only a plain reordering, and only when nothing objects:

• adding a model the chain never held, or dropping one, always waits for you;
• a movement without evidence stops the pass;
• a source that did not answer that day stops the pass, because the ranking then stood on less than it should;
• the operator’s global dispatch switch stops it, like everything else that acts on its own.

Every unattended outcome is written to the audit log — including the passes that changed nothing, with the reason. Under Autonomous, calibration still runs when you press the button; only the automatic applying is off.