# How to Configure Fallback Targets in OmniRoute: A Complete Guide to Resilient AI Routing

> Configure OmniRoute fallback targets for resilient AI routing. Learn to set global defaults, tiered redundancy, and account-specific strategies for seamless failover.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-01

---

**Configure fallback targets in OmniRoute at three levels: set a `globalFallbackModel` as a last-resort default, define `fallbackTier` and `fallbackDelayMs` within combo definitions for tiered redundancy, and customize `fallbackStrategy` per account or provider to control how the router selects alternatives when primary targets fail.**

OmniRoute's routing engine provides layered fallback configuration to ensure your AI requests succeed even when primary models experience outages, rate limits, or quota exhaustion. This guide explains how to configure fallback targets across global, combo, and account levels using the actual implementation in `diegosouzapw/OmniRoute`.

## Global Fallback Model: The Last Line of Defense

The **global fallback model** serves as a single, final destination when all other routing attempts fail. This setting is stored in the database's *settings* key-value table and applied in [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts) (lines 860-870).

### Setting the Global Fallback

The global fallback is stored as a JSON string identifying a provider/model combination:

```ts
// Using the internal DB helper
await db.run("settings", "globalFallbackModel", JSON.stringify("openai/gpt-4o-mini"));

```

The handler reads this value after exhausting combo and account-level fallbacks. The implementation deliberately restricts this to a **single model** to prevent infinite recursion chains.

### Global Fallback in the Request Flow

In [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts), the fallback logic executes between lines 859-892:

1. The router attempts all models in the current combo
2. If exhausted, it checks for combo-level `fallbackTier`
3. When no tiered fallback exists or succeeds, it reads `globalFallbackModel` from settings
4. The request is forwarded to that model with original error context preserved

## Combo-Level Fallback: Tiered Redundancy

Combos support granular fallback configuration through three fields defined in [`src/shared/validation/schemas/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/combo.ts) (lines 97-159):

| Field | Purpose | Typical Value |
|-------|---------|-------------|
| `fallbackTier` | Name of another combo to try when primary fails | `"fallback-combo"` |
| `fallbackDelayMs` | Milliseconds to wait before invoking fallback | `200` |
| `fallbackCompressionMode` | Whether to compress request before retry | `"gzip"` or `null` |

### Example Combo with Fallback Tier

```json
{
  "name": "fast-chat",
  "targets": [
    { "provider": "openai", "model": "gpt-4o-mini" },
    { "provider": "anthropic", "model": "claude-3-haiku-20240307" }
  ],
  "fallbackTier": "fallback-combo",
  "fallbackDelayMs": 200
}

```

The `fallbackTier` creates a **directed graph of combos**—each can point to another, building chains of arbitrary depth (though practical deployments typically use 2-3 tiers).

## Account and Provider Fallback Strategies

Before escalating to combo or global fallbacks, OmniRoute attempts **account-level recovery** using configurable strategies.

### Available Fallback Strategies

The strategy enumeration lives in [`src/shared/validation/settingsSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/settingsSchemas.ts) (lines 207-210):

- **`"fill-first"`** — Exhaust all quota on current account before switching
- **`"round-robin"`** — Distribute failures evenly across available accounts
- **`"least-used"`** — Select the account with lowest recent request count

### Provider Override Configuration

Override strategies per provider in the `provider_overrides` table. The merge logic resides in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts) (lines 1486-1490):

```ts
await db.run(
  "provider_overrides",
  "openai",
  JSON.stringify({ 
    fallbackStrategy: "least-used", 
    stickyRoundRobinLimit: 5 
  })
);

```

Here `stickyRoundRobinLimit` prevents excessive switching by keeping requests bound to an account until the limit is reached.

## Explicit Fallback Chains (Advanced)

For precise control over provider ordering, define a **fallback chain** using the schema in [`src/shared/validation/schemas/routing.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/routing.ts) (lines 19-31):

```ts
{
  "chain": [
    { "provider": "openai", "model": "gpt-4o-mini" },
    { "provider": "groq", "model": "mixtral-8x7b-32768" },
    { "provider": "anthropic", "model": "claude-3-5-sonnet-20241022" }
  ]
}

```

Chains bypass combo resolution entirely, forcing the router to try providers in exact sequence. This is useful for **disaster recovery scenarios** where specific provider combinations must be attempted in priority order.

## Complete Fallback Execution Flow

OmniRoute evaluates fallbacks in strict priority:

1. **Combo resolution** — Expand request's combo and try each target model
2. **Account fallback** — Apply `fallbackStrategy` to select alternative accounts for the same provider
3. **Combo fallback** — When all accounts exhausted, check `fallbackTier` and repeat steps 1-2
4. **Global fallback** — Read `globalFallbackModel` setting and forward request
5. **Error propagation** — Return original error if global fallback fails

Success at any step terminates the chain and returns the response to the client.

## Database Migration Example

The `globalFallbackModel` key is populated during migrations. See [`tests/unit/db-core-migration.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/db-core-migration.test.ts) (lines 57-66) for the initialization pattern:

```ts
// Excerpt from migration test
await db.run("settings", "globalFallbackModel", JSON.stringify("anthropic/claude-3-haiku-20240307"));

```

## Summary

- **Global fallback** provides universal resilience through a single `globalFallbackModel` setting applied in [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts)
- **Combo fallbacks** enable tiered architecture using `fallbackTier`, `fallbackDelayMs`, and `fallbackCompressionMode` defined in [`src/shared/validation/schemas/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/combo.ts)
- **Account strategies** control intra-provider recovery via `fallbackStrategy` values validated in [`src/shared/validation/settingsSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/settingsSchemas.ts) and merged in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts)
- **Explicit chains** override all routing logic with ordered provider sequences from [`src/shared/validation/schemas/routing.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/routing.ts)
- Configure via database API calls or direct JSON insertion; test migrations demonstrate proper key initialization

## Frequently Asked Questions

### What happens if both combo fallback and global fallback are configured?

The router attempts the combo's `fallbackTier` first. Only when that tier is exhausted or undefined does it read `globalFallbackModel`. This two-stage design lets you prioritize domain-specific fallbacks before resorting to the global default.

### Can I disable fallback entirely?

Omit `fallbackTier` from all combos and leave `globalFallbackModel` unset (or set to `null`). Without these configurations, the router propagates the original error immediately when primary targets fail.

### How does `fallbackDelayMs` interact with rate limit headers?

The delay executes unconditionally before attempting the fallback tier. It does not parse `Retry-After` headers. For header-aware backoff, implement custom middleware or adjust `fallbackDelayMs` based on observed provider behavior.

### Why is `globalFallbackModel` restricted to a single model?

The implementation in [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts) enforces this to prevent recursive fallback chains. A single terminal endpoint guarantees termination and simplifies reasoning about worst-case routing behavior.