Guide

Rate limits

Limits protect every application from abuse and keep latency predictable. Development and staging run relaxed limits for fast iteration; production runs real ones. When you exceed a limit, the API returns 429 with error.code: rate_limited.

Reading the headers

Every response carries the standard rate-limit headers. Use RateLimit-Remaining to pace ahead of a limit, and honor Retry-After (seconds) on a 429 before retrying.

HTTP headers

RateLimit-Limit: 600
RateLimit-Remaining: 599
RateLimit-Reset: 41
Retry-After: 41

Backing off cleanly

On a 429, wait for Retry-After and retry with exponential backoff. The same pattern covers transient 5xx responses. Authentication-sensitive routes (sign-in, verify, MFA) are limited more tightly than reads — expect to back off sooner on those.

JavaScript

async function withRetry(fn, tries = 4) {
  for (let i = 0; ; i++) {
    const res = await fn();
    if (res.status !== 429 || i >= tries) return res;
    const wait = Number(res.headers.get("Retry-After") ?? 2 ** i);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}