> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Rate limits and quotas
> Understand how the AI Gateway enforces plan-based request limits, budget-based cost, token, and requests-per-minute limits, and what a 429 response looks like.
**Orq.ai** enforces limits at three layers. Every request to the **AI Gateway** passes a plan-based platform rate limit, any **Budget** limits that match the request, and finally the upstream provider's own quotas. Knowing which layer rejected a request is the first step to fixing it.
| Layer | Enforced by | Configurable | Applies to |
| -------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------- |
| Platform rate limits | **Orq.ai**, per workspace plan | Custom plans by arrangement | Every request to the gateway |
| Budget limits | **Orq.ai**, from configured budgets | Yes, under **Settings > Organization > [Budgets](/docs/ai-gateway/budgets)** | Requests matching the budget scope |
| Provider rate limits | The upstream provider account | By the provider | Requests routed to that provider |
## Platform rate limits
Each workspace is limited to a fixed number of requests per minute based on its subscription. When the limit is reached, requests are rejected with `429 Too Many Requests` until the rolling 60-second window resets.
| Plan | Requests per minute | Requests per day |
| ------------- | --------------------------- | ---------------- |
| Free | 20 | 50 |
| Pay as you go | 100 | No cap |
| Custom | 1500, higher by arrangement | No cap |
* Limits use a **rolling 60-second window**, the same window that applies to budget requests-per-minute limits.
* The daily cap applies to the Free plan only.
* Custom plans can arrange higher per-minute limits with **Orq.ai**.
* On-premise deployments are licensed rather than metered: plan-based limits do not apply. A single system-wide cap can be enforced with the `ORQ_SYSTEM_RPM_LIMIT` environment variable.
Platform limit rejections return `429` with a `Retry-After` header and the `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers.
## Budget limits
[Budgets](/docs/ai-gateway/budgets) apply configured limits to a named target. A budget defines one or more limits: **Cost** in USD, **Tokens**, and **Requests per minute**. See [Budgets](/docs/ai-gateway/budgets) for how to configure them.
Requests per minute always uses a rolling 60-second window, **independent of the reset period**. A monthly budget's `50 req/min` still allows 50 requests in any single minute and resets its request counter 60 seconds after the first request in the window, not at month end. The reset period (Daily, Weekly, Monthly, Yearly, One-time) applies to cost and token limits only.
### Limits on an API key
API keys do not carry limit fields of their own. Set cost, token, or requests-per-minute limits on a key by creating a [Budget](/docs/ai-gateway/budgets) scoped to that **API Key**. The key's remaining capacity is visible in the budget's detail page, and its cost and token capacity in the `X-RateLimit-*-Cost` and `X-RateLimit-*-Tokens` response headers.
The unsuffixed `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers report the plan's platform rate limit on a successful request, not a budget's requests-per-minute limit, because the platform limiter writes them last. A budget's requests-per-minute values appear in these headers only on a `429` raised by that budget. Read budget request consumption from the budget's detail page instead.
Legacy API keys, created before the current unified key model, do not support budget-based cost, token, or rate limits. Create a current API key and scope a [Budget](/docs/ai-gateway/budgets) to it instead.
## Multiple limits on one request
A request can match several budgets at once: for example, a budget scoped to the workspace and another scoped to the calling API key. Every matching budget is enforced, and each tracks its own usage. The most restrictive applicable limit binds. See [Budget levels and interaction](/docs/ai-gateway/budgets#budget-levels-and-interaction) for the full rules and worked examples.
## The 429 response
When any limit is exceeded, the gateway returns `429 Too Many Requests` with an OpenAI-compatible error body. Budget rejections carry `scope_kind`, `scope_target_id`, and `dimension`:
```json Budget rejection (requests per minute) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"error": {
"message": "Rate limit exceeded. Maximum requests allowed per minute.",
"type": "rate_limit_error",
"param": null,
"code": "requests_per_minute_exceeded",
"scope_kind": "workspace",
"scope_target_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"dimension": "requests"
}
}
```
The `code` and `dimension` identify the exceeded limit:
| Code | Dimension | Limit |
| ------------------------------ | ---------- | --------------------------------------- |
| `rate_limit_exceeded` | (absent) | Platform rate limit (subscription plan) |
| `requests_per_minute_exceeded` | `requests` | Budget requests per minute |
| `cost_budget_exceeded` | `cost` | Budget cost |
| `token_budget_exceeded` | `tokens` | Budget tokens |
`scope_kind` and `scope_target_id` identify which budget rejected the request and are present only on budget rejections. The `message` text varies by limit type; use the `code` field for programmatic matching.
### Rate limit headers
Rate limit headers are emitted per dimension, and each group of three is present only when that dimension applies to the request. A response therefore carries some of these headers, not all of them. Headers appear on successful requests (showing remaining capacity) as well as on rejections.
| Header | Meaning | When present |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit` | Requests per minute allowed by the plan's platform rate limit | On every gateway request |
| `X-RateLimit-Remaining` | Requests left in the current window | On every gateway request |
| `X-RateLimit-Reset` | Seconds until the window resets (e.g. `42s`) | On every gateway request |
| `X-RateLimit-Limit-Daily` | Daily request limit | Free plan only |
| `X-RateLimit-Remaining-Daily` | Requests left in the daily window | Free plan only |
| `X-RateLimit-Reset-Daily` | Seconds until the daily window resets (e.g. `42s`) | Free plan only |
| `X-RateLimit-Limit-Tokens` | Token limit | Only when a matching budget sets a token limit |
| `X-RateLimit-Remaining-Tokens` | Tokens left in the current period | Only when a matching budget sets a token limit |
| `X-RateLimit-Reset-Tokens` | Seconds until the token counter resets (e.g. `42s`) | Only when a matching budget sets a token limit |
| `X-RateLimit-Limit-Cost` | Cost limit in USD | Only when a matching budget sets a cost limit |
| `X-RateLimit-Remaining-Cost` | Cost remaining in the current period (in USD) | Only when a matching budget sets a cost limit |
| `X-RateLimit-Reset-Cost` | Seconds until the cost counter resets (e.g. `42s`) | Only when a matching budget sets a cost limit |
| `Retry-After` | Seconds until the rejecting limit resets, as a plain integer (e.g. `42`). The `X-RateLimit-Reset*` headers use the `42s` format instead | Rejections only |
Two cases drop headers that the table otherwise lists as always present. The unsuffixed `X-RateLimit-*` triplet is omitted when the request carries no workspace context, and in on-premise deployments unless `ORQ_SYSTEM_RPM_LIMIT` is set. `Retry-After` is omitted when a rejected budget never resets on a clock, such as a **One-time** budget.
### Retries and fallbacks
`429` is retryable. The gateway's [Retries](/docs/ai-gateway/features/retries) feature retries on `429` by default with exponential backoff and honors the `Retry-After` header, and [fallbacks](/docs/ai-gateway/features/retries#fallbacks) route to a backup model when the primary is rate-limited. Retries run inside the gateway on a single incoming request (the platform rate limiter counts inbound client requests, not upstream calls), so they do not consume additional platform or budget quota.
## See also
Create budgets with cost, token, and requests-per-minute limits and configure alerts.
How budgets at different levels interact when several apply to the same request.
Create and manage **AI Gateway** API keys, then scope a budget to cap usage.
Retry rate-limited requests with backoff and route to fallback models.