Skip to content
Get started

Rate limits

Each API key can make 50 requests per second. The limit is the same on every plan, and responses tell you how much of it is left.

The limit

Applies toLimitNotes
Single lookups50 requests per second, per keyCounted per key, so two keys do not share a window.
Bulk jobsNot subject to the per-second limitRows are processed in the background. Submit the list once.

If you need a higher sustained rate, contact us with your expected volume.

Headers

Every response carries the state of your limit.

HeaderMeaning
X-RateLimit-LimitRequests allowed per second for this key.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-ResetWhen the current window resets.
Retry-AfterSent with a 429. Seconds to wait before the next request.

When you exceed it

The request is rejected with 429 and the rate_limited error code. Nothing ran, so nothing is charged.

Response headers
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
Retry-After: 1
429 Too Many Requests
{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Wait for the Retry-After interval."
  },
  "meta": {
    "credits_used": 0,
    "credits_remaining": 999,
    "cached": false,
    "request_id": "req_8f3a2c1e9b7d"
  }
}

Backing off

Wait for the Retry-After interval, add a little jitter so parallel workers do not retry together, and cap the number of attempts.

async function lookup(url, body, key, attempt = 0) {
  const res = await fetch(url, {
    method: "POST",
    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  if (res.status === 429 && attempt < 5) {
    const wait = Number(res.headers.get("Retry-After") ?? 1) * 1000;
    const jitter = Math.random() * 250;
    await new Promise((r) => setTimeout(r, wait + jitter));
    return lookup(url, body, key, attempt + 1);
  }
  return res.json();
}

Staying under the limit

  • For a list, use the bulk API instead of a tight loop. One job replaces thousands of requests.
  • Give each service its own key so one busy worker cannot starve another.
  • Deduplicate inputs before you send them, so you do not spend requests on values you already have.