Docs
Rate limits & budgets
Rate limits, per-key daily budgets, the response headers, and when each resets.
Two kinds of ceiling
Rate limits come from your plan and bound speed. Budgets are set on the key itself and bound total spend. They are independent, and either can reject a request on its own.
Rate limits
| Window | Error code |
|---|---|
| Requests per minute | rate_limit_rpm |
| Requests per hour | rate_limit_rph |
| Requests per day | rate_limit_rpd |
| Tokens per minute | rate_limit_tpm |
Read your key's current limits without opening the dashboard:
bash
curl https://iranrouter.com/v1/key -H "Authorization: Bearer ir-..."Response headers
| Header | Meaning |
|---|---|
x-ratelimit-limit-requests | The current window's ceiling |
x-ratelimit-remaining-requests | What is left in that window |
x-ratelimit-reset-requests | Seconds until reset |
x-ratelimit-limit-tokens | Tokens-per-minute ceiling |
retry-after | On any 429: how many seconds to wait |
x-request-id | The request ID — quote this to support |
Always honour
retry-after. An agent that retries immediately just exhausts its own window faster.Per-key daily budget
Each key can carry a daily token ceiling, a daily Rial ceiling, or both. The ceiling is hard: a request whose estimate would cross it does not run — it is not run-then-warn.
- Rejection:
429withkey_daily_token_budget_reachedorkey_daily_budget_reached - Reset: Tehran midnight. The retry-after header carries the exact seconds until then.
- To unblock sooner, raise the ceiling. The usage counter cannot be zeroed — otherwise a daily budget would mean nothing.
Before leaving an autonomous agent running, put a daily budget on its key. One bad loop can burn hundreds of thousands of tokens overnight.
Monthly cap
On top of the daily budget a key can carry a monthly spend cap; crossing it returns 402 monthly_cap_reached.