> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Fallbacks & reliability

> Configure a fallback model on Rightbrain tasks and agents, force the fallback for testing, and read the per-model usage split.

Model providers have outages, rate limits, and occasional bad responses. A fallback model gives a task or agent a second model to fall back to when the primary one fails, so a single provider problem does not take your production runs down with it.

## How fallbacks work

Both tasks and agents let you set a **fallback model** alongside the primary model on their revision:

* **Tasks** carry `fallback_llm_model_id` on the task revision.
* **Agents** carry a fallback model on the agent revision.

When a run's primary model fails, Rightbrain automatically retries the call on the fallback model. The switch is transparent to the caller — the run continues and returns a result if the fallback succeeds. Failover happens mid-run and preserves progress; it doesn't restart the run from the top.

The run records that it happened: `used_fallback_model` flips to `true`, `primary_failure_reason` captures why the primary was abandoned, and `model_usages` carries a per-model split — each model's `call_count`, tokens, and credits. A run might show two calls on the primary before it failed and three on the fallback that finished the job, so you can see the failover and what it cost in one record. You are not trading reliability for observability — support sees the failure reason and finance sees the per-model split.

> **Warning**
>
> Task fallback excludes timeout errors. Agent model fallback includes timeout errors. A client disconnect is different: it cancels the live agent execution, so inspect the stored run before retrying it.

Because the fallback model is part of the revision, it is versioned with everything else. Changing it creates a new revision; rolling back restores the previous pairing.

## Forcing the fallback for testing

You don't have to wait for a real outage to confirm your fallback behaves. Task runs accept a `use_fallback_model` query parameter that forces the run onto the fallback model:

**`Force the fallback model on a task run`**

```bash title="Force the fallback model on a task run"
curl -X POST \
  "https://app.rightbrain.ai/api/v1/org/$ORG_ID/project/$PROJECT_ID/task/$TASK_ID/run?use_fallback_model=true" \
  -H "Authorization: Bearer $RB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "task_input": { "text": "hello" } }'
```

Use this to check that your fallback model produces acceptable output before you depend on it in an incident.

## Chaos Mode

Forcing a fallback proves the alternate model can answer. [Chaos testing](/docs/production/chaos-testing) exercises the surrounding recovery path with bounded, deterministic model and tool faults on a single agent run. Use it to verify failover telemetry, retry policy, malformed-result handling, and latency tolerance before release.

## Per-model usage split

Runs record how much work each model did, split by type (`primary` vs `fallback`) and scope (`reasoning` vs `memory_compaction` — core reasoning versus the cost of compacting an agent's memory across a long run). The split appears in the agent [usage reports](/docs/production/observability); a rising share of `fallback` usage is an early signal that your primary provider is degrading.

## Retry posture

* Fallback is a **model-level** retry: primary model fails, the fallback model is tried.
* Task fallback excludes timeouts; agent model fallback includes them.
* For an ambiguous HTTP response or disconnect, inspect run status and completed tool actions before retrying. Repeating a run request can create duplicate work.

> **Tip**
>
> Choose a fallback model from a different provider than your primary where you can. A fallback on the same provider won't help you during that provider's outage.

## Related

#### [Observability & audit](/docs/production/observability)

Read the per-model usage and credit reports.

#### [Versioning & revisions](/docs/production/revisions)

Fallback models are part of the versioned revision.

#### [Run tasks via API](/docs/api/run-tasks)

Task run options, including `use_fallback_model`.

#### [Chaos testing](/docs/production/chaos-testing)

Inject replayable model and tool faults into a test run.

#### [Tasks](/docs/concepts/tasks)

Where primary and fallback models are configured.