# How the Priority Routing Strategy Works in OmniRoute

> Discover how OmniRoute's priority routing strategy works. Learn how lower priority values are attempted first for successful routing.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts)** — declares `priority` as a supported strategy constant
- **[`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```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, `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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts) | Strategy enumeration including `"priority"` |
| [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) | Target resolution and priority sorting logic |
| [`src/lib/db/connections.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.