How the Priority Routing Strategy Works in OmniRoute

The "priority" routing strategy in OmniRoute sorts combo targets by ascending priority value (lower numbers first) and attempts them sequentially until one succeeds.

OmniRoute is an open-source LLM gateway that routes requests through combos — ordered lists of provider and model targets. Each combo specifies a routing strategy that controls how the engine selects targets and handles failures. The "priority" strategy is the default and simplest approach, giving operators fine-grained control over failover order.

What Is the Priority Routing Strategy?

The priority strategy determines target selection based on a numeric priority field assigned to each connection (account). When a combo uses this strategy, OmniRoute builds a candidate list and sorts targets by ascending priority value, meaning lower numbers indicate higher preference.

This deterministic ordering guarantees that your preferred accounts are always tried before backup alternatives. The strategy is defined in two core locations:

• src/shared/constants/routingStrategies.ts — declares priority as a supported strategy constant
• open-sse/services/combo.ts — implements the resolveComboTargets() function that performs priority-based sorting

How Priority Target Resolution Works

When a request arrives for a combo using the priority strategy, the resolution process follows these steps:

1. Build candidate list — gather all targets matching the combo's provider/model specifications
2. Apply tag filters — if metadata.tags are specified, filter to accounts matching any tag
3. Sort by priority — order remaining targets by ascending priority value
4. Execute sequentially — attempt each target in order until success or exhaustion

The resolveComboTargets() function in open-sse/services/combo.ts handles this logic directly, returning a ResolvedComboTarget[] array ready for execution.

Priority Strategy Behavior During Failures

The priority strategy implements exhaustive sequential fallback:

• On rate limits, network errors, or other failures, the engine immediately proceeds to the next target in the sorted list
• Cooldowns and circuit-breakers temporarily remove affected targets from the candidate set, automatically promoting the next highest-priority available target
• If all targets fail, the request surfaces as a combo-level error — no additional providers are consulted beyond those explicitly defined in the combo

This behavior makes priority ideal for scenarios where you have primary/secondary/tertiary accounts with the same provider and want predictable, deterministic failover.

Defining a Combo with Priority Routing

Below is a complete combo configuration that uses the priority strategy with multiple accounts for the same model:

{
  "name": "my-priority-combo",
  "strategy": "priority",
  "models": [
    {
      "provider": "openai",
      "model": "gpt-4o",
      "account": "primary-openai",
      "overrides": {}
    },
    {
      "provider": "openai",
      "model": "gpt-4o",
      "account": "backup-openai",
      "overrides": {}
    }
  ],
  "config": {}
}

In this example, primary-openai has priority: 1 while backup-openai has priority: 5. OmniRoute will always attempt the primary account first, falling back to the backup only if the primary fails.

Where Priority Is Stored and Configured

The priority strategy depends on data from three key files across the OmniRoute codebase:

File	Purpose
src/shared/constants/routingStrategies.ts	Strategy enumeration including "priority"
open-sse/services/combo.ts	Target resolution and priority sorting logic
src/lib/db/connections.ts	Account records with priority field storage

The priority field itself is a numeric property on each connection record, typically configured during account setup in the connections database.

When to Use Priority vs. Other Strategies

Choose the priority routing strategy when you need:

• Deterministic ordering — guaranteed execution sequence based on explicit rankings
• Provider-level failover — multiple accounts with the same provider, one preferred
• Simple predictability — easy to reason about which target handles each request

Consider alternative strategies from src/shared/constants/routingStrategies.ts when you need load balancing, latency-based selection, or cost optimization rather than explicit priority ordering.

Summary

• The priority routing strategy is OmniRoute's default approach for combo target selection
• Targets are sorted by ascending priority value (lower = higher priority) in resolveComboTargets() within open-sse/services/combo.ts
• The strategy provides deterministic, sequential failover through all defined targets
• Tag filters and cooldowns modify the candidate set before priority sorting occurs
• All target failures result in a combo-level error — no automatic cross-provider fallback

Frequently Asked Questions

What happens if two accounts have the same priority value?

When multiple accounts share identical priority values, their relative order is determined by the stable sort implementation in resolveComboTargets(). While consistent within a single OmniRoute version, you should assign unique priorities for predictable, documented behavior.

Can I change priority values without restarting OmniRoute?

Priority values are stored in src/lib/db/connections.ts and typically loaded at runtime. Check your specific deployment configuration — many OmniRoute setups support dynamic configuration reloading, though this depends on your caching and deployment architecture.

Does the priority strategy work across different providers?

The priority strategy operates strictly within a combo's defined targets. If your combo includes OpenAI and Anthropic accounts, they are sorted together by priority regardless of provider. However, the strategy does not automatically search outside the combo — you must explicitly include all desired providers and accounts in the combo definition.

How does priority interact with request retries?

OmniRoute's retry logic operates at the target level — each priority-ranked target may have its own retry configuration. After a target's retries are exhausted, the engine advances to the next priority level. The priority itself determines which target to try next, not how many attempts occur per target.

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