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 two kinds of limits. Rate limits cap how fast requests arrive and return 429 rate_limit_exceeded. Spend limits cap what a key, team, or budget may settle and return 402. Both responses carry x-nr-limit-source, a header that names exactly which limit fired, so a client never has to guess whether to slow down or top up.
Rate limits (429)
A 429 returns the error code rate_limit_exceeded, a Retry-After header with the wait in seconds, and x-nr-limit-source set to the scope that fired:
| Source | Meaning |
|---|---|
key | The API key's own rate limit. |
team | The team's shared rate limit. |
user | The user's rate limit. |
plan | The plan's rate limit. |
capacity | Provider capacity for the model at that moment. |
plan_window_h8 / plan_window_day / plan_window_week | A plan allowance window — 8-hour, daily, or weekly — is exhausted. |
plan_allowance_exhausted | The plan allowance is used up. |
plan_required | The request needs a plan allowance the account does not have. |
When an allowance is exhausted, x-nr-allowance-reset gives the time it resets. Honour Retry-After instead of retrying immediately; an immediate retry counts against the same limit.
Spend limits (402)
A 402 means the request was refused before any provider call because there was nothing to settle against:
| Code | Meaning |
|---|---|
insufficient_credits | The account balance does not cover the request. |
budget_exceeded | A budget ceiling fired; x-nr-limit-source reads budget. |
Budgets are set per key, team, or organization in Budget Controls, and balances are managed in Billing & Credits.
What to do when you hit one
- Read
x-nr-limit-source— it separates "slow down" (429) from "top up or raise a ceiling" (402). - On a
429, wait theRetry-Afterinterval and checkx-nr-allowance-resetfor window limits. - On a
402, add credits or raise the budget ceiling that fired; the request succeeds as soon as the balance or ceiling covers it.