How OmniRoute Tracks Free‑Tier Quotas Across 90+ LLM Providers

OmniRoute tracks free‑tier quotas using a three‑layer system: live usage APIs where available, self‑tracking counters driven by a static catalog for providers without APIs, and error‑driven exhaustion detection as a safety net.

OmniRoute is an open‑source LLM routing layer that aggregates 90+ model providers into a unified API. Managing free‑tier limits across this many providers—each with different rate limits, reset windows, and no standard usage endpoints—requires a robust quota enforcement system. This article breaks down exactly how the codebase implements this, from static configuration files to real‑time request counting.

The Three‑Layer Quota Architecture

The system treats every provider's free tier as a quota‑limited resource and applies three complementary enforcement mechanisms depending on provider capabilities.

Layer 1: Static Free‑Tier Catalog

OmniRoute maintains a compiled list of free‑tier limits in open‑sse/config/freeModelCatalog.data.ts. This catalog defines RPM (requests per minute), daily request caps, token limits, and reset cadences for each model.

The catalog is refreshed from upstream provider announcements—for example, when "minimax‑m3‑free" was removed—and is consulted on every routing decision to free models. It serves as the single source of truth for providers that expose no usage API.

Layer 2: Live Quota Pre‑Flight

For providers that do expose usage endpoints—such as XAI/Grok, Vertex AI, and V0—the open‑sse/services/quotaPreflight.ts service executes a preflightQuota() call before the actual LLM request.

This call returns a Quota object containing one or more windows (weekly, monthly, etc.) with:

• used: current consumption
• total: allocated limit
• percentUsed: utilization percentage
• resetAt: next reset timestamp

The retrieved data is cached both in‑memory via the quota monitor and in a database‑backed cache for persistence across restarts.

import { preflightQuota } from "@/open-sse/services/quotaPreflight";
import { clearQuotaMonitors } from "@/open-sse/services/quotaMonitor";

await clearQuotaMonitors();                       // reset caches for a clean test
const quota = await preflightQuota("xai", {
  connectionId: "conn-123",
});
console.log(quota?.windows?.monthly?.percentUsed);

Layer 3: Self‑Tracking Quota Monitor

For the majority of providers with no published usage endpoint, OmniRoute falls back to open‑sse/services/quotaMonitor.ts. This lightweight self‑tracker maintains per‑connection counters keyed by connection ID.

On each request, the monitor:

1. Looks up the provider's free‑tier limits from the static catalog
2. Increments the appropriate window counter (monthly, weekly, etc.)
3. Resets counters automatically when resetAt is reached based on documented reset cadences

The recordRequest() function returns a boolean indicating whether quota remains, allowing the routing layer to block or redirect requests before they hit the provider.

import { recordRequest } from "@/open-sse/services/quotaMonitor";

async function callFreeModel(connId: string, model: string) {
  // Check quota before sending
  const canProceed = await recordRequest(connId, model);
  if (!canProceed) throw new Error("Free-tier quota exhausted");

  // ... invoke the actual executor (e.g. opencode-zen) ...
}

Error‑Driven Quota Exhaustion Detection

Even with pre‑flight checks, free tiers can exhaust mid‑flight due to race conditions or provider‑side attribution. OmniRoute handles this via open‑sse/services/accountFallback.ts and open‑sse/services/antigravity429Engine.ts.

The error classification rules detect:

• HTTP 402 or 429 with response bodies containing "free tier of the model has been exhausted"
• Provider‑specific codes such as 403 with {"error": "quota exceeded"}

Once detected, open‑sse/services/quotaMonitor.ts marks the quota window as exhausted, and the combo‑router avoids that connection for the remainder of the window—preventing wasted retries on depleted credentials.

Integration with the Combo Router

The quota status from either path (live or self‑tracked) feeds into auto‑combo strategies via open‑sse/services/autoCombo/virtualFactory.ts. Strategies like free‑only combos query the monitor before target selection, guaranteeing free quota is never over‑consumed.

import { getComboTargets } from "@/open-sse/services/combo";
const targets = await getComboTargets({
  strategy: "auto/coding:free",   // free-tier-only combo
  request,
});

The routing layer in open‑sse/services/accountFallback.ts uses this status to decide whether to skip a free‑tier connection or fall back to a paid key.

Key Implementation Files

Concern	File Path
Static free‑tier limits	open‑sse/config/freeModelCatalog.data.ts
Live quota pre‑flight	open‑sse/services/quotaPreflight.ts
Self‑tracking monitor	open‑sse/services/quotaMonitor.ts
Error classification & fallback logic	open‑sse/services/accountFallback.ts
Free‑tier exhaustion detection	open‑sse/services/antigravity429Engine.ts
Auto‑combo factory integration	open‑sse/services/autoCombo/virtualFactory.ts
Provider rankings & free‑tier flags	src/lib/freeProviderRankings.ts
Quota plan registry	src/lib/quota/planRegistry.ts

Summary

• Static catalog (freeModelCatalog.data.ts) provides baseline limits for all 90+ providers
• Pre‑flight API calls (quotaPreflight.ts) fetch live usage where providers support it
• Self‑tracking counters (quotaMonitor.ts) enforce limits when no API exists
• Error‑driven detection (antigravity429Engine.ts, accountFallback.ts) catches quota exhaustion in real time
• Combo router integration ensures free‑only strategies respect limits across the entire request lifecycle

Frequently Asked Questions

How does OmniRoute handle providers that expose no usage API?

For providers without usage endpoints, OmniRoute relies on quotaMonitor.ts to self‑track requests. It increments counters against limits defined in freeModelCatalog.data.ts and resets them based on documented provider cadences. This covers the majority of free‑tier providers in the system.

What happens when a free‑tier quota is exhausted mid‑request?

The antigravity429Engine.ts service classifies provider errors indicating exhaustion, and accountFallback.ts marks the quota window as depleted in quotaMonitor.ts. The combo‑router then excludes that connection from subsequent routing decisions until the window resets.

Can I query quota status before sending a request?

Yes. Call preflightQuota() from quotaPreflight.ts for providers with live APIs, or recordRequest() from quotaMonitor.ts for self‑tracked providers. Both return boolean or structured quota data you can check before invoking the actual model executor.

How does OmniRoute prevent double‑counting across multiple instances?

Live quota data is persisted to a database‑backed cache in addition to in‑memory storage. Self‑tracked counters remain instance‑local by design, but accountFallback.ts error detection converges state across instances when providers signal exhaustion.

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