Rate limits

Every API key has a budget of 100 requests per second. Read the RateLimit-* headers, handle 429 responses and retry only after Retry-After.

How the limit works#

The limit belongs to each API key, not to the account: two keys of the same utility have separate budgets. A key can make 100 requests per second, counted in one-second windows. When the server keeps the counts in its database, every replica shares the same window; if that shared count fails, each process enforces the same budget on its own.

The limit covers every API area (Business, Consumer, Platform, Public and Connector) whenever a request presents a key. Requests made with a dashboard session or an OAuth token skip this limiter and do not get the headers below. Rotating a key gives the replacement a new ID, and with it a budget of its own.

Headers on every response#

Every response to a key-authenticated request carries three headers:

Header Meaning
RateLimit-Limit Requests allowed per window (100).
RateLimit-Remaining Requests left in the current window.
RateLimit-Reset Seconds, rounded up, until the window starts again.

Once the budget is spent, the response is 429 Too Many Requests and also carries Retry-After, set to the same value as RateLimit-Reset.

bash
curl -sS -i "$BUSINESS_API/customers?limit=1" \
  -H "Authorization: Bearer $API_KEY"
http
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1
Request-Id: req_7f3a9c21d04b4e6f8a12b5c9e0d7f364

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "This API key (sk_rtest_C3J2) exceeded its request budget; retry after the RateLimit-Reset seconds.",
  "instance": "$BUSINESS_API/customers",
  "code": "RATE_LIMITED",
  "error_code": "request.rate_limited",
  "request_id": "req_7f3a9c21d04b4e6f8a12b5c9e0d7f364"
}

The detail names the key by its prefix, never by its secret. When the operator has configured the documentation site, type points to the request.rate_limited anchor on the errors page; otherwise it is about:blank. Branch on error_code, not on the text.

Retry safely#

  1. Read RateLimit-Remaining on each response and slow down as it nears zero.
  2. On a 429, wait the number of seconds in Retry-After, then send the same request again.
  3. For POST requests that create resources, resend the same Idempotency-Key, so a refused request that you retry never creates two records.
javascript
async function withLimit(url, options, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") || "1");
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    return res;
  }
  throw new Error("key budget exhausted");
}

The gotactl CLI does this for you: on a 429 it waits Retry-After (one second when the header is missing) and tries twice more; if the third attempt is refused too, it exits with code 5.

Other limits#

Some endpoints that take no key, such as public requests and sign-in, have budgets of their own and also answer 429 with Retry-After, but without the RateLimit-* headers. Key requests refused by the limiter still appear under Developers > Logs with status 429.

Next steps#