# Rate limits
> Two-level fixed-window limits, X-RateLimit response headers, and 429 handling.

REST API (`/v1`) requests are rate limited by two levels of fixed-window counters; **exceeding either returns 429**:

| Level | Quota | Window |
| --- | --- | --- |
| Account | 600 requests/min | 60s |
| API key | 120 requests/min | 60s |

These quotas are platform-wide settings: every account and every API key has the same quota, and they are not configured per account.

## Response headers

These headers are sent only on the `429` (`rate_limited`) response, not on successful responses:

| Header | Description |
| --- | --- |
| `Retry-After` | Seconds to wait before retrying |
| `X-RateLimit-Limit-Tenant` / `X-RateLimit-Remaining-Tenant` | Account-level quota / remaining |
| `X-RateLimit-Limit-Key` / `X-RateLimit-Remaining-Key` | Key-level quota / remaining |
| `X-RateLimit-Reset` | Seconds until the quota resets |

## Handling 429

```json
{
  "error": {
    "code": "rate_limited",
    "type": "rate_limit_error",
    "message": "Tenant rate limit exceeded",
    "retryable": true,
    "details": {
      "scope": "tenant",
      "limit": 600,
      "window_seconds": 60,
      "retry_after_seconds": 12
    },
    "request_id": "req_..."
  }
}
```

`details.scope` names the exceeded level (`tenant` or `api_key`) and `details.limit` is its quota; `details.retry_after_seconds` equals the `Retry-After` header. `tenant` means the whole account; `api_key` means this one key.

- Honor the `Retry-After` header (seconds) on the 429, then retry with the **same** `Idempotency-Key`;
- Bursty concurrency is the most common trigger; smooth out requests on the client side;
- Need a higher quota? Contact us via the console or your account manager.