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.
curl -sS -i "$BUSINESS_API/customers?limit=1" \
-H "Authorization: Bearer $API_KEY"
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#
- Read
RateLimit-Remainingon each response and slow down as it nears zero. - On a
429, wait the number of seconds inRetry-After, then send the same request again. - For
POSTrequests that create resources, resend the sameIdempotency-Key, so a refused request that you retry never creates two records.
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.