Skip to content

DevelopersGuides

Rate limits

Buckets, the global limit, headers and 429s.

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.

BucketWith a keyWithout a key (per IP)Routes
search60/min10/min/minecraft/servers, /discord/servers, /discord/bots
item180/min20/min/minecraft/servers/{slug}, /minecraft/servers/{slug}/events, /discord/servers/{slug}, /discord/bots/{slug}
history60/min10/min/minecraft/servers/{slug}/history, /discord/servers/{slug}/history, /discord/bots/{slug}/history
meta60/min20/min/minecraft/modes, /tags, /stats
lookup30/min5/min/lookup
global300/min30/minAll of the above together

Headers

HeaderMeaning
X-RateLimit-LimitRequests the route's bucket allows per window.
X-RateLimit-RemainingRequests left in the window.
X-RateLimit-ResetUnix time in seconds (with decimals) when the window resets.
X-RateLimit-Reset-AfterSeconds until it resets (with decimals).
X-RateLimit-BucketThe 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-After is whole seconds; retry_after in the body is exact. X-RateLimit-Scope is user for a bucket and global for the global limit (then X-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.