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

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 (lines 860-870).

Setting the Global Fallback

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

// 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, 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 (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

{
  "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 (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 (lines 1486-1490):

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 (lines 19-31):

{
  "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 (lines 57-66) for the initialization pattern:

// 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
• Combo fallbacks enable tiered architecture using fallbackTier, fallbackDelayMs, and fallbackCompressionMode defined in src/shared/validation/schemas/combo.ts
• Account strategies control intra-provider recovery via fallbackStrategy values validated in src/shared/validation/settingsSchemas.ts and merged in src/sse/services/auth.ts
• Explicit chains override all routing logic with ordered provider sequences from 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 enforces this to prevent recursive fallback chains. A single terminal endpoint guarantees termination and simplifies reasoning about worst-case routing behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}