> ## Documentation Index
> Fetch the complete documentation index at: https://manifest.build/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fallback

> Set up a fallback chain so a provider outage or rate limit returns a working response instead of an error.

## What is fallback?

When a model fails (provider outage, rate limit, bad request), Manifest retries with a backup model from the same tier. Your agent gets a response instead of an error.

## How it works

<Steps>
  <Step title="Request fails">
    The primary model returns an error (any HTTP 4xx or 5xx status).
  </Step>

  <Step title="Manifest selects a backup">
    Manifest picks the next fallback model from the tier's fallback list. Fallback models are tried in the order you configure them.
  </Step>

  <Step title="Request is retried">
    The original request is forwarded to the backup model. If that model also fails, Manifest continues down the fallback list until a model succeeds or all options are exhausted.
  </Step>
</Steps>

## What triggers a fallback

Any HTTP status code **>= 400** triggers a fallback, with one exception: **424 (Failed Dependency)** does not trigger a fallback (this is the status Manifest itself returns when the entire chain is exhausted, preventing infinite loops).

This includes:

| Status  | Example               |
| ------- | --------------------- |
| **400** | Bad request           |
| **401** | Authentication error  |
| **403** | Forbidden             |
| **429** | Rate limited          |
| **500** | Internal server error |
| **502** | Bad gateway           |
| **503** | Service unavailable   |
| **529** | Provider overloaded   |

## Configuration

Fallback models are configured **per tier** in the Manifest dashboard. Each tier can have up to **5 fallback models**, tried in order.

<Steps>
  <Step title="Open Routing in the dashboard">
    Navigate to **Routing** in the dashboard.
  </Step>

  <Step title="Select a tier">
    Click your Default tier or any custom tier.
  </Step>

  <Step title="Add fallback models">
    Add up to 5 fallback models. Drag to reorder — models are tried from top to bottom.
  </Step>
</Steps>

## Hung providers and the per-attempt timeout

A provider that opens a connection but never returns will eventually trigger a fallback via Manifest's per-attempt timeout (default 180 seconds), which surfaces as a synthetic `504 Gateway Timeout` and triggers the next model in the chain.

If your upstream client (e.g. an agent gateway) has its own timeout that fires at the same time, the client may disconnect first and Manifest will give up before reaching a healthy fallback. On self-hosted installs, lower `PROVIDER_TIMEOUT_MS` strictly below your client's timeout so the fallback chain has room to run within the client's window. See [Self-hosted](/self-hosted) for the env var reference.

## Response headers

When a fallback succeeds, the response carries `X-Manifest-Fallback-From` (the primary that failed) and `X-Manifest-Fallback-Index` (its position in the chain) on top of the standard routing headers. When the chain is exhausted, `X-Manifest-Fallback-Exhausted: true` is set and the request returns `424`. Full table: [Headers reference](/reference/headers).

## Fallback vs routing

|           | Routing                        | Fallback                            |
| --------- | ------------------------------ | ----------------------------------- |
| **When**  | Before the request is sent     | After the request fails             |
| **Goal**  | Pick the model for the request | Recover from a failure              |
| **Speed** | In-process, no extra call      | Adds one extra round-trip per retry |
| **Tier**  | Picks the tier                 | Stays within the same tier          |

Routing picks the model. Fallback catches it if that model is down.

<Tip>
  Connect at least two providers. With a single provider, fallback can only switch between that provider's models.
</Tip>