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

> Learn how OmniRoute tracks free tier quotas across 90+ LLM providers. Discover its three layer system: live APIs, self tracking, and error detection for reliable usage monitoring.

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

---

**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.

```typescript
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.

```typescript
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.

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/freeProviderRankings.ts) |
| Quota plan registry | [`src/lib/quota/planRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/planRegistry.ts) |

## Summary

- **Static catalog** ([`freeModelCatalog.data.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/freeModelCatalog.data.ts)) provides baseline limits for all 90+ providers
- **Pre‑flight API calls** ([`quotaPreflight.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/quotaPreflight.ts)) fetch live usage where providers support it
- **Self‑tracking counters** ([`quotaMonitor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/quotaMonitor.ts)) enforce limits when no API exists
- **Error‑driven detection** ([`antigravity429Engine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/antigravity429Engine.ts), [`accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/quotaMonitor.ts) to self‑track requests. It increments counters against limits defined in [`freeModelCatalog.data.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/antigravity429Engine.ts) service classifies provider errors indicating exhaustion, and [`accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/accountFallback.ts) marks the quota window as depleted in [`quotaMonitor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/quotaPreflight.ts) for providers with live APIs, or `recordRequest()` from [`quotaMonitor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/accountFallback.ts) error detection converges state across instances when providers signal exhaustion.