Docs / Getting started

Rate limits and errors

Request limits, the 429 response, and the shape of every error.

Limits

Who	Requests per minute	Contributions per hour
No key	120, per address	none
User key	600	200 submissions and photo uploads
Bot or admin key	6,000	unlimited

Over the limit, the API answers 429 with a Retry-After header in seconds. Wait that long and try again.

Every error is JSON with a plain-English error:

{ "error": "Item not found" }

Validation errors add details, one entry per problem:

{
  "error": "Invalid request",
  "details": [{ "path": "/payload/data/min_players", "message": "Invalid input: expected number" }]
}

Status	Meaning
`400`	The request is malformed; see `details`
`401`	The request needs a key: contributing, or a photo without its signed link
`403`	The key may not do this (for example, admin functions)
`404`	Nothing at that id or slug. Merged items redirect to the survivor instead
`409`	A conflict, such as an email that is already taken
`413`	A photo over the size limit
`429`	Rate limited; see `Retry-After`

Cache responses. Items change rarely; updated_at tells you when.
Page with limit (up to 200) and offset.
Poll GET /v1/events?after=<id> for changes instead of re-reading everything. See History.
Send a User-Agent that names your app, so we can reach you if something goes wrong.