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

> Discover how OmniRoute's priority routing strategy works. Learn its technical implementation for sequential provider targeting and automatic fallback on errors.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: technical-implementation-guide
- Published: 2026-07-22

---

** 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts)** – Declares the supported strategies array, including the `"priority"` constant that enables this routing mode.
- **[`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)** – Houses the `resolveComboTargets()` function, which implements the sorting logic and target resolution.
- **[`src/lib/db/connections.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```json
{
  "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`](https://github.com/diegosouzapw/OmniRoute/blob/main/routingStrategies.ts), sorting logic in [`combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/combo.ts), and data storage in [`connections.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts). When a combo specifies `"strategy": "priority"`, the system invokes the resolution logic in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) to handle target selection and ordering.