Rate limits
How many requests per minute and hour, what headers we return, and how to back off.
Limits
The Public API enforces two limits per token:
- 60 requests / minute (burst)
- 5,000 requests / hour (sustained)
Both are evaluated on every request. Whichever is exceeded first wins.
Response headers
Every authenticated response includes:
| Header | Meaning |
|---|---|
X-RateLimit-Bucket | Which bucket was checked (publicAPI:token:min or …:hr) |
X-RateLimit-Limit | The limit for that bucket |
X-RateLimit-Remaining | Requests left in the current window |
X-RateLimit-Reset | Unix timestamp (seconds) when the bucket resets |
When you exceed a limit, the response is 429 TOO_MANY_REQUESTS with a
Retry-After header (seconds) telling you how long to wait:
Best practices
- Honor
Retry-After— don't retry sooner than it says. - Cache responses on your end where it makes sense; the server already returns
Cache-Control: private, no-cacheso intermediate caches don't share data, but you can keep your own per-process cache. - For periodic polling (e.g., "check every 60s if I have new saves"), use a smart interval rather than the minimum.
Brute-force protection
Requests with no token, malformed tokens, or unknown tokens are rate-limited by IP at 30 requests per minute as a brute-force deterrent.