Errors & rate limits

Every error is JSON with a stable error shape and the right HTTP status. No surprises, no HTML error pages.

Error shape

401 · response
{
  "error": {
    "type": "unauthorized",
    "message": "Missing or invalid API key."
  }
}

Status codes

200OK — request succeeded.
400Bad request — a parameter is missing or malformed.
401Unauthorized — missing or invalid API key.
404Not found — no data for that id / platform.
429Too many requests — you hit the rate limit.
5xxServer error — retry with backoff.

Rate limits

The free tier allows generous bursts. Every response includes your remaining quota so you never have to guess.

  • X-RateLimit-Limit — requests allowed in the current window.
  • X-RateLimit-Remaining — requests left.
  • X-RateLimit-Reset — unix seconds until the window resets.

On 429, back off until the reset time — the SDK does this automatically.