Limits

How nRouter limits work: rate-limit windows, allowances, budget limits, the 429 and 402 responses, and the headers that say which limit fired.

nRouter enforces deterministic request-rate throttling and credit-spend ceilings to ensure provider reliability and prevent runaway costs. Rate limits restrict request velocity and token volume, returning HTTP 429 with rate_limit_exceeded. Spend limits cap account balance burn across keys, teams, and budgets, returning HTTP 402. Both refusal responses emit the x-nr-limit-source header to distinguish rate throttling from funding exhaustion immediately.

Rate limits (429)

Throttles request velocity and token volume across four metrics: RPM (Requests Per Minute), TPM (Tokens Per Minute), RPS (Requests Per Second), and RPD (Requests Per Day). A 429 returns rate_limit_exceeded, Retry-After, and x-nr-limit-source:

Source	Meaning
`key`	API key rate limit (RPM, TPM, RPS).
`team`	Team shared rate limit (RPM, TPM).
`user`	User rate limit.
`plan`	Organization plan ceiling (RPM, TPM, RPS, RPD).
`capacity`	Temporary upstream provider capacity constraint.
`plan_window_h8` / `plan_window_day` / `plan_window_week`	Allowance window (8-hour, daily, or weekly) exhausted.

When an allowance window is exhausted, x-nr-allowance-reset indicates reset timing.

Sliding-Window Rate Limit Clamping

nRouter enforces sliding-window rate limits across three hierarchical tiers:

effective_rate_limit = min(key_limit, team_limit, plan_limit)

Hierarchical clamping: For RPM and TPM, the gateway evaluates the minimum ceiling across key, team, and plan scopes (LEAST(key_limit, team_limit, plan_limit)). Team rate limits define an aggregate ceiling across all keys assigned to the team, while key limits restrict individual request velocity.
RPS and RPD metrics: RPS enforces per-key sliding-log rate limits bounded by the organization plan ceiling, while RPD regulates daily request volume against plan ceilings.
Pre-flight enforcement: The gate evaluates rate limits in-memory before forwarding inference to any upstream provider. If any tier or metric is saturated, the gateway immediately returns HTTP 429 rate_limit_exceeded with the triggering tier named in x-nr-limit-source.

Spend limits (402)

Indicates pre-flight refusal when funds are depleted:

Code	Meaning
`insufficient_credits`	Account balance depleted; requests pause until reload.
`budget_exceeded`	Budget ceiling breached; `x-nr-limit-source` returns `budget`.
`plan_allowance_exhausted`	Plan allowance used up.
`plan_required`	Legacy subscription plan allowance is paused pending payment (PAYG accounts use credits and never receive this code).

Configure ceilings in Budget Controls and balances in Billing & Credits.

Mitigation

Check x-nr-limit-source to distinguish rate throttling (429) from spend ceilings (402).
On 429, back off for Retry-After seconds and track x-nr-allowance-reset.
On 402, add credits in Billing & Credits or adjust limits in Budget Controls.

Frequently asked questions

Is a 402 a rate limit?

No, HTTP 402 indicates spend exhaustion, while HTTP 429 indicates rate or allowance throttling.

What does x-nr-limit-source: capacity mean?

The upstream provider temporarily lacked capacity; retrying after Retry-After or using a fallback resolves it.

Where is the full list of response headers?

See Response Headers for headers and Errors & Rate Limits for all error codes.