Rate limits and errors

Limits apply per app key and per IP address.

Rate limit headers

Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. When a limit is reached the API responds with HTTP 429, code RATE_LIMITED, and a Retry-After header in seconds.

Error codes

Error response format

Errors return success: false with a code and a human-readable message:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after 21 seconds."
  }
}

Handling 429s

• Watch X-RateLimit-Remaining and slow down before you hit zero.
• On a 429, wait the number of seconds in Retry-After, then retry — do not retry immediately.
• For backfills, page with limit=100 and stay under 60 requests per minute; a full year of daily rows is at most a few requests per endpoint.