Rate limits
The gateway applies several layers of rate limiting to keep the service stable and usage fair.
Limit layers
| Layer | Scope | Description |
|---|---|---|
| Key spending cap | A single API key | Maximum spend, with optional automatic reset (daily / weekly / monthly) |
| Balance check | A single user | Requests are rejected when the balance reaches zero |
| Token quota | User / group | Daily token ceiling (for example 500K tokens per day) |
| RPM | User / route | Maximum requests per minute |
| Concurrency | A single user | Maximum simultaneous requests |
Precedence
When the same kind of limit is configured at more than one layer:
Consumer (user) > Consumer group > Route (global)The more specific setting wins — a per-user limit overrides the limit on its group.
Response headers
Every response carries OpenAI-compatible rate limit headers:
X-RateLimit-Limit-Tokens: 500000
X-RateLimit-Remaining-Tokens: 495000
X-RateLimit-Reset-Tokens: 1711929600Rate limit errors
| Status | Meaning |
|---|---|
| 403 | Insufficient balance, or the key's spending cap has been reached |
| 429 | Token quota, RPM or concurrency limit exceeded |
Back off and retry after a short wait. X-RateLimit-Reset-Tokens tells you when the quota resets.