Rate limits

The limits#

• Without a key60 calls a minute per IP address, for every route together.
• With a keyThe key's own limit, for every route together, whatever address it comes from.
• Uploads600 a minute per address on /captures: the mod sends a session's files at once.
• IconsNot counted: a page shows dozens.

The minute slides: calls from the last minute count, the older ones for less as they age, so there is no moment when everything resets at once.

Where you stand#

Every counted answer says it in three headers:

• RateLimit-LimitYour calls a minute.
• RateLimit-RemainingHow many are left right now.
• RateLimit-ResetSeconds until the current minute ends (when none are left: until one is free again).

Over the limit#

The answer is a 429 with Retry-After in seconds and a JSON error:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many calls: 60 a minute is the free limit; for more, ask for an API key. Try again in 12 s."
  }
}

Spending less#

• Take the whole list once. /items without filters gives every item in one call; keep it, and ask again only when it changed.
• Send ETags back. A 304 still counts, but costs almost nothing to send and to receive. See Caching.
• Poll the version. The root route is tiny and says the catalogue version: fetch the big lists only when it changes.