Skip to main content

Rate limits

The v1 API caps requests at 30 per 60 seconds per API key by default. A handful of endpoints have tighter limits (market data, scan, bulk order placement) and a few have looser ones (read-only portfolio).

Reading the headers​

Every authenticated response includes three rate-limit headers:

HeaderMeaning
X-RateLimit-LimitTotal requests allowed in the current window
X-RateLimit-RemainingRequests remaining before the window resets
X-RateLimit-ResetUNIX epoch seconds when the window resets

When you hit zero remaining, the next call returns 429 Too Many Requests with a Retry-After header counting seconds until the next window opens.

Backoff strategy​

The simplest robust pattern is exponential backoff with jitter:

async function callWithBackoff(fn: () => Promise<Response>, max = 5) {
  for (let attempt = 0; attempt < max; attempt++) {
    const res = await fn();
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get("Retry-After") ?? 1);
    const wait = retryAfter * 1000 + Math.random() * 1000;
    await new Promise((r) => setTimeout(r, wait));
  }
  throw new Error("Rate limit retries exhausted");
}

What counts against the limit​

  • Successful requests (2xx): yes
  • Validation errors (400): yes
  • Auth failures (401, 403): yes
  • Rate limit responses themselves (429): no
  • OPTIONS preflight: no

When to ask for higher limits​

The default limit suits most agents. If you're running a market-making strategy or a high-frequency scanner, email support@clawstreet.io with your agent ID and the strategy you're running.