Limits work like Discord's. Each route belongs to a bucket, counted per key (or per IP without one), and every key also has a global limit across all routes. Windows last a minute from a bucket's first request.
| Bucket | With a key | Without a key (per IP) | Routes |
|---|---|---|---|
| search | 60/min | 10/min | /minecraft/servers, /discord/servers, /discord/bots |
| item | 180/min | 20/min | /minecraft/servers/{slug}, /minecraft/servers/{slug}/events, /discord/servers/{slug}, /discord/bots/{slug} |
| history | 60/min | 10/min | /minecraft/servers/{slug}/history, /discord/servers/{slug}/history, /discord/bots/{slug}/history |
| meta | 60/min | 20/min | /minecraft/modes, /tags, /stats |
| lookup | 30/min | 5/min | /lookup |
| global | 300/min | 30/min | All of the above together |
Headers
| Header | Meaning |
|---|---|
| X-RateLimit-Limit | Requests the route's bucket allows per window. |
| X-RateLimit-Remaining | Requests left in the window. |
| X-RateLimit-Reset | Unix time in seconds (with decimals) when the window resets. |
| X-RateLimit-Reset-After | Seconds until it resets (with decimals). |
| X-RateLimit-Bucket | The bucket's id. Routes with the same id share a limit. |
When you hit one
Over a limit you get 429 and nothing is counted. global tells a spent global limit from a spent bucket:
HTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Global: false
X-RateLimit-Scope: user
X-RateLimit-Bucket: search
X-RateLimit-Remaining: 0
{
"message": "You are being rate limited on the search bucket.",
"retry_after": 17.42,
"global": false
}Retry-Afteris whole seconds;retry_afterin the body is exact.X-RateLimit-Scopeisuserfor a bucket andglobalfor the global limit (thenX-RateLimit-Global: true).- Responses may be cached for the time in
Cache-Control(30 seconds for status, 5 minutes for history): polling faster gets the same data. - Need more? Tell us what you're building.