Rate Limits

Understand API rate limits and how to handle them.

Rate Limits by Plan

Authenticated requests are limited per API key and per account plan. The stricter bucket controls the response headers for the current request.

The limit is a rolling 60-second window, not a per-second cap. There is no separate requests-per-second ceiling to pace against — spread requests evenly across the minute and the window never fills early.

Handling 429s

When a key or account window is exhausted, the API returns 429 with rate-limit headers and Retry-After. Pause and retry with exponential backoff:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 37 seconds.",
    "request_id": "10cf9db1-90f7-493f-ab85-93e1e155c18f"
  }
}

Use X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Policy, and Retry-After to pace retries.

Best Practices

• Implement exponential backoff (with jitter) when you receive a 429
• Use batch endpoints to reduce request count
• Cache verification results when appropriate