Rate limits

View as Markdown

In short

Each API key can make 300 requests a minute, and each client IP address 600 a minute across all keys. Thirty failed authentications a minute from one IP lock it out briefly. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; a 429 carries Retry-After.

The limits

Limit Applies to Window
300 requests Each API key Per minute
600 requests Each client IP address, across all keys and including unauthenticated requests Per minute
30 failed authentications Each client IP address. Only requests with a missing or invalid key count Per minute
60 sign-in links Each API key, on POST /users/{id}/sign-in-links, on top of the limits above Per minute

The limits are the same on every plan. A valid key is never locked out by failed authentication from the same IP address, so one misconfigured client on a shared network can't block the others.

If your integration needs more, tell us what it does and how many requests you expect.

Headers

Successful responses carry the per-key budget:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287

The per-key limit is the one that normally runs out first, so it is the one these headers report. On responses to requests without a valid key, they report the per-IP limit instead.

A request over a limit gets 429 Too Many Requests with a Retry-After header, in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
{
  "error": {
    "type": "rate_limited",
    "message": "Too many requests. Retry after the period in the Retry-After header."
  },
  "request_id": "01M70B3D5XN0PQR2S4T6V8W0YZ"
}

Staying inside the limits

  • Use limit=100 on list endpoints: one request instead of four.
  • Sync changes, not everything. Use updated_since and the other change filters (see Pagination), or webhooks instead of polling.
  • Watch X-RateLimit-Remaining and slow down as it approaches zero.
  • On a 429, wait for Retry-After before trying again. Don't retry in a tight loop: the failed retries count too.
  • Retry POSTs with the same Idempotency-Key, so a retry after a timeout can't create something twice. See Idempotency.
async function call(url, options = {}, attempt = 0) {
  const res = await fetch(url, options);
  if (res.status === 429 && attempt < 5) {
    const wait = Number(res.headers.get('Retry-After') || 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return call(url, options, attempt + 1);
  }
  return res;
}

Frequently asked questions

Do idempotent replays count against the limit?

Yes. A replayed response is still a request, so it uses one from the key's budget.

Are the limits per team or per key?

Per key, plus the per-IP limit. Two keys in the same team each have their own 300 a minute, but if they run on the same server they share that server's 600 a minute.

Building an integration?

Tell us what you are connecting and we will help you plan it, or book a demo to see the API working.