# 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

- [Retry without duplicates using Idempotency-Key](/docs/getting-started/idempotency)
- [Error format and the list of codes](/docs/getting-started/errors)
- [Rotate a key without breaking the integration](/docs/getting-started/api-keys)

