Rate limiting

HTTP/1.1 200 OK
RateLimit-Limit: 300
RateLimit-Reset: 8

// `signRequest({ method, url, body })` returns { headers, body } with a freshly minted JWT
// AND a freshly computed X-Request-Signature each call. See the Authentication guide.
async function callWithBackoff(
  { method, url, body },
  signRequest,
  maxRetries = 5,
) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    // Mint per attempt: JWT TTL is 60s; backoff loops can exceed that, and the
    // signature is bound to the JWT's nonce so capturing once is doubly broken.
    const signed = signRequest({ method, url, body });
    const res = await fetch(url, {
      method,
      headers: signed.headers,
      body: signed.body,
    });

    if (res.status !== 429) return res;

    // Rate limited: Retry-After and RateLimit-Reset are both a number of
    // seconds to wait, NOT an epoch timestamp. Number(null) is 0 (which
    // passes isFinite!), so check for a missing header explicitly rather
    // than letting Number() coerce it — otherwise a response with neither
    // header retries immediately instead of falling back to backoff.
    const waitHeader =
      res.headers.get("retry-after") ?? res.headers.get("ratelimit-reset");
    const wait = waitHeader === null ? NaN : Number(waitHeader);
    const waitMs = Number.isFinite(wait)
      ? wait * 1000
      : 1000 * (attempt + 1); // fall back to linear backoff
    await sleep(waitMs);
  }
  throw new Error("Rate limit retry budget exhausted");
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "type": "RATE_LIMITED",
    "message": "Too many requests. Try again after the window resets.",
    "retryStrategy": "WAIT_THEN_RETRY_SAME_KEY",
    "details": {}
  }
}

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 300
RateLimit-Reset: 8
Retry-After: 8
X-Trace-Id: 4bf92f3577b34da6a3ce929d0e0e4736
X-Request-Timestamp: 2026-05-29T12:34:56.789Z