Routing Rules

A routing rule decides which gateway serves each request for a FreeRouter key. Two strategies: a weighted %-split, or a priority order with failover. Attach one rule per key.

How rules work

Every FreeRouter key is bound to exactly one routing rule. A rule references the providers you've added to the workspace and lists them as targets. When a request arrives, FreeRouter evaluates the rule, picks a target, swaps in that provider's key, and forwards the request. If a model isn't available on the chosen target, FreeRouter skips to the next eligible target.

Percentage split

A split rule distributes requests across targets by weight. Use it to run a cost/performance blend, A/B two gateways, or gradually shift traffic. Weights are relative; FreeRouter normalizes them to 100%.

Example — 70/30 cost blend

Send most traffic to a cheaper gateway, the rest to a faster one:

{
  "strategy": "split",
  "targets": [
    { "provider": "openrouter", "weight": 70 },
    { "provider": "vercel",     "weight": 30 }
  ]
}

Roughly 7 in 10 requests go to OpenRouter, 3 in 10 to the Vercel AI Gateway. Selection is per request, so both gateways see live traffic continuously.

Example — canary a new gateway

Start a new provider at a small share, then raise its weight as you gain confidence:

{
  "strategy": "split",
  "targets": [
    { "provider": "openrouter", "weight": 95 },
    { "provider": "cloudflare", "weight": 5 }
  ]
}

Priority with failover

A failover rule lists targets in priority order. FreeRouter always tries the first healthy target; if it errors, times out, or is rate limited, FreeRouter automatically retries the next target down the list, and so on.

Example — primary + backups

{
  "strategy": "failover",
  "targets": [
    { "provider": "openrouter", "priority": 1 },
    { "provider": "vercel",     "priority": 2 },
    { "provider": "cloudflare", "priority": 3 }
  ]
}

OpenRouter serves normally. If a request to it fails, FreeRouter retries the same request against Vercel, then Cloudflare, before returning an error. The X-FreeRouter-Attempts response header reports how many targets were tried.

What triggers a failover

• Connection errors or timeouts from the upstream gateway.
• 5xx responses from the gateway.
• 429 rate-limit responses.
• The requested model isn't offered by that target.

Client errors that would recur everywhere — like a malformed body (400) — are not retried; FreeRouter returns them immediately.

Split vs. failover

One rule per key

Because each FreeRouter key carries its own rule, you can run different strategies side by side without touching code. A common setup:

• Production key — failover for maximum uptime.
• Batch/offline key — split weighted toward the cheapest gateway.
• Evaluation key — split 50/50 to compare two gateways head-to-head.