All requests to the Gradual Public API are rate-limited to ensure fair usage and platform stability. Rate limits are applied per tenant and vary based on the type of operation.
Operation Tiers
Each API request is classified into one of three tiers:
| Tier | Description | Examples |
|---|---|---|
| Light | Single resource reads | GET /users/:id, GET /events/:id |
| Medium | List queries and write operations | GET /users, POST /registration, DELETE /users |
| Heavy | Batch and bulk operations | POST /users/batch, POST /clubs/:id/users/batch |
Rate Limits
Each tier has two independent limits:
| Tier | Burst Rate | Sustained Rate | Daily Quota |
|---|---|---|---|
| Light | 100 requests | 10 req/sec | 300,000/day |
| Medium | 10 requests | 1 req/sec | 10,000/day |
| Heavy | 5 requests | ~10 req/min | 200/day |
- Burst rate: The maximum number of requests you can make in a short burst.
- Sustained rate: How quickly your allowance replenishes over time.
- Daily quota: The maximum total requests per day (resets at midnight UTC).
Response Headers
Every response includes headers so you can monitor your usage:
| Header | Description |
|---|---|
X-RateLimit-Limit | Sustained requests per second allowed |
X-RateLimit-Remaining | Burst tokens remaining |
X-RateLimit-Burst | Maximum burst capacity |
X-RateLimit-Reset | Unix timestamp when burst tokens fully replenish |
X-RateLimit-Daily-Limit | Total requests allowed per day |
X-RateLimit-Daily-Remaining | Requests remaining today |
X-RateLimit-Daily-Reset | Unix timestamp of next daily reset (midnight UTC) |
When You're Rate Limited
If you exceed either limit, the API returns a 429 (Too Many Requests) response with a Retry-After header indicating how many seconds to wait before retrying.