How OmniRoute's Priority Routing Strategy Works: Technical Implementation Guide

** OmniRoute's priority routing strategy sorts provider targets by ascending numeric priority values (lower equals higher priority) and attempts them sequentially, automatically falling back to the next available target when errors occur. **

The priority routing strategy serves as the default routing mechanism in OmniRoute, an open-source LLM gateway developed by diegosouzapw/OmniRoute. This strategy provides deterministic control over which provider accounts handle incoming requests by leveraging simple numeric rankings that dictate failover order.

Core Concept: Ordered Target Selection

OmniRoute processes requests through a combo—an ordered list containing specific provider and model targets. Each target within a combo references an account (connection) that includes a configurable priority property. When a combo utilizes the priority routing strategy, the engine builds a candidate list and sorts it by these priority values before attempting connections.

The lower the priority number, the earlier the target appears in the execution sequence. For example, an account with priority: 1 is always attempted before an account with priority: 5.

Implementation Architecture

Three critical files define the priority strategy's behavior:

• src/shared/constants/routingStrategies.ts – Declares the supported strategies array, including the "priority" constant that enables this routing mode.
• open-sse/services/combo.ts – Houses the resolveComboTargets() function, which implements the sorting logic and target resolution.
• src/lib/db/connections.ts – Defines the database schema where each account's priority field is stored and retrieved.

The resolveComboTargets() Logic

The resolveComboTargets() function in open-sse/services/combo.ts handles the expansion and ordering of targets. Its execution flow follows these steps:

1. Expansion: Resolves the combo definition into an array of concrete ResolvedComboTarget objects.
2. Filtering: If the combo specifies metadata.tags, the function filters the candidate list to include only accounts matching those tags.
3. Sorting: Sorts the remaining targets in ascending order by the priority property (lowest numeric value first).
4. Cooldown Removal: Excludes any targets currently in cooldown or circuit-breaker state from the candidate set.
5. Return: Passes the ordered array to the request executor.

Sequential Fallback Behavior

Once the sorted list is generated, the router attempts the first target. If that target returns an error—such as a rate limit, authentication failure, or network timeout—the engine immediately proceeds to the next target in the priority-sorted list. This sequential retry continues until:

• A target returns a successful response, or
• The engine exhausts all available targets in the combo.

When all targets fail, OmniRoute surfaces a combo-level error and stops processing. The priority strategy does not consult additional providers beyond those defined in the combo.

Configuration Example

Define a priority-based combo in your OmniRoute configuration:

{
  "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, if primary-openai has priority: 1 and backup-openai has priority: 5, OmniRoute attempts the primary account first. Only if that fails does it route to the backup.

Summary

• Lower numbers win: The priority strategy sorts targets by ascending numeric priority, where 1 ranks higher than 10.
• Deterministic ordering: The same combo configuration always yields the same execution order, ensuring predictable failover behavior.
• Tag filtering: Metadata tags filter the candidate list before priority sorting occurs.
• Exhaustive retries: The router attempts every target in the sorted list before failing the request.
• Source locations: Strategy definition lives in routingStrategies.ts, sorting logic in combo.ts, and data storage in connections.ts.

Frequently Asked Questions

What priority values should I assign to my accounts?

Use any numeric values; the strategy only cares about relative ordering. Lower numbers indicate higher priority, so assign 1 to your preferred primary account, 2 to your secondary, and so on. The system treats priority: 0 as higher priority than priority: 1.

How does priority routing handle targets that are rate limited?

If a target is currently in a cooldown or circuit-breaker state, resolveComboTargets() temporarily removes it from the candidate set before sorting. The router then attempts the next highest-priority available target, ensuring failed providers do not block requests.

Does the priority strategy support weighted distribution?

No. The priority strategy implements strict deterministic ordering rather than weighted or probabilistic distribution. Every request for a given combo starts with the same highest-priority target. For load distribution across multiple healthy targets, you would need to implement a different strategy or configure multiple combos.

Where does the routing engine check which strategy to use?

The engine references the strategy identifier against the constants defined in src/shared/constants/routingStrategies.ts. When a combo specifies "strategy": "priority", the system invokes the resolution logic in open-sse/services/combo.ts to handle target selection and ordering.

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