Rate limits

Requests are rate limited per API key using a sliding window. Limits are set on your account, so a narrow key used by one integration cannot exhaust the budget of another. If you need a higher limit, ask.

Headers

Every response carries the current state of your window, so you do not have to guess.

When you are limited

You get 429 with type of rate_limit_error.

{
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12s.",
    "request_id": "req_8a3f21bc"
  }
}

Wait at least Retry-After seconds, then retry. Add exponential backoff and jitter on top, because a fleet of workers that all retry at exactly Retry-After simply recreates the spike.

async function call(request, attempt = 0) {
  // Fetch a clone: a Request body can only be read once, so sending the
  // original would make any retry of a POST fail with a used-body error.
  const res = await fetch(request.clone());
  if (res.status !== 429 || attempt >= 5) return res;

  const retryAfter = Number(res.headers.get("Retry-After") ?? 1);
  const jitter = Math.random() * 0.3 * retryAfter;
  await new Promise((r) => setTimeout(r, (retryAfter + jitter) * 1000));
  return call(request, attempt + 1);
}

Staying under the limit

The largest avoidable source of traffic is polling. If you are calling the retrieve endpoint on a timer waiting for a verdict, subscribe to webhooks instead and the traffic disappears. Use the list endpoint for reconciliation sweeps rather than for detecting individual changes, and page with starting_after rather than re-reading from the top.

Bulk work

If you need to create a large number of verifications in a burst, for example a batch re-verification of an existing user base, spread the work over time and talk to us first. We would rather raise your limit deliberately than have you discover it at three in the morning.