Rate limits

The API limits the number of requests per time window. Once the limit is exceeded, the request is rejected with 429 without being executed: it consumes no quota and produces no effects.

The window is one minute and the counter starts on each clock minute, not on the first request. A burst straddling two minutes is split across both counters.

Applicable limit

The counter depends on whether the request carries credentials and on the host serving it:

Several clients behind one server do not compete for a single per-IP counter: each account counts on its own with the limit of its plan. The per-IP ceiling is a guard against abuse, and every key coming from the same origin shares it.

Certain operations apply stricter limits of their own because of their cost or sensitivity, such as sign-in, OTP delivery and broadcasts, and declare them on their reference page.

Limits per plan

An account without a plan, or on a plan with no value of its own, takes the values of the free plan. GET /v1/usage/limits returns the ones that apply to the authenticated account.

Webhooks

Deliveries to the same destination host have two caps, and each delivery needs room under both:

A delivery that does not fit is not lost. It is deferred and retried on the schedule described in webhooks architecture.

The 429 response

{
  "errors": [
    {
      "status": "429",
      "code": "rate_limit_exceeded",
      "detail": "Request limit exceeded."
    }
  ],
  "meta": { "version": "1.57.0", "api_version": "v1", "request_id": "e6f7a8b9c0d1" }
}

The response includes the headers needed to retry without guessing:

On the API, a X-RateLimit-Limit of 1,200 identifies the per-IP ceiling; any other value is the per-key limit of the plan.

Consumption on every response

Every response of the API to a request with an API key carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for the per-key counter, not only the 429. Remaining can be read to space out calls before reaching the limit.

X-RateLimit-Limit: 240
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1790812860

The rest of the surfaces, and the requests without credentials, emit these headers only on 429 responses. A repetition of an idempotent operation answered from the stored result does not go through the limiter and does not carry them.

Recommended handling

The Retry-After value is the only data needed to retry: wait that margin and repeat the request. Retrying earlier consumes the counter again and extends the block.

Rate limits protect the system against bursts, not against total volume. Monthly volume is governed by the plan quota and its own error codes, described in the error taxonomy.