Guide

Stay within rate limits

The public API returns rate-limit headers on successful responses and on 429 responses. Read the headers and slow down before retrying.

Response headers

Header	Description
X-RateLimit-Limit	Limit for the current request bucket.
X-RateLimit-Remaining	Remaining requests in the current bucket.
X-RateLimit-Reset	Unix timestamp for the bucket reset.
Retry-After	Seconds to wait before retrying. Present on rate-limited responses.

429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1779120000
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "The request was rate limited. Retry later.",
    "request_id": "req_...",
    "details": {
      "retry_after_seconds": 60
    }
  }
}

Client behavior

Throttle proactively when X-RateLimit-Remaining gets low.
On 429, wait at least Retry-After seconds before retrying.
Use exponential backoff and jitter when many workers share a key.
Do not retry malformed requests; fix 4xx errors that are not rate limits.