Rate limits and quotas

To keep the API fast for everyone, requests are rate limited per key. Your plan sets the ceiling, and every response tells you where you stand.

Reading the headers

• X-RateLimit-Limit — the maximum requests allowed in the current window.
• X-RateLimit-Remaining — how many you have left.
• X-RateLimit-Reset — a UTC timestamp for when the window resets.

Handling a 429

If you exceed the limit you receive a 429 Too Many Requests response with a Retry-After header. Respect it. The cleanest approach is exponential backoff with jitter so retries do not all fire at once.

if (res.status === 429) {
  const wait = Number(res.headers.get("Retry-After")) || 1
  await sleep((wait + Math.random()) * 1000)
  // retry the request
}

If you consistently bump against the limit, prefer webhooks over tight polling, or talk to us about a higher quota on your plan.