Rate limits

​

Default limits

​

How the window works

​

Response headers

​

429 response shape

{
  "error": {
    "code": "rate_limit.exceeded",
    "message": "Rate limit exceeded for this API key. Wait for the Retry-After window to expire before retrying.",
    "status": 429,
    "retryable": true,
    "request_id": "req_..."
  }
}

​

Retry strategy

async function requestWithRetry(url, options, maxAttempts = 4) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const retryAfter = Number(response.headers.get("retry-after")) || 1;
    const jitterMs = Math.floor(Math.random() * 500);
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitterMs));
  }
  throw new Error("Rate-limited after retries");
}

import time, random, requests

def request_with_retry(method, url, max_attempts=4, **kwargs):
    for attempt in range(max_attempts):
        response = requests.request(method, url, **kwargs)
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("retry-after", "1"))
        time.sleep(retry_after + random.uniform(0, 0.5))
    raise RuntimeError("Rate-limited after retries")

func requestWithRetry(client *http.Client, req *http.Request, maxAttempts int) (*http.Response, error) {
    for attempt := 0; attempt < maxAttempts; attempt++ {
        resp, err := client.Do(req)
        if err != nil {
            return nil, err
        }
        if resp.StatusCode != 429 {
            return resp, nil
        }
        retryAfter, _ := strconv.Atoi(resp.Header.Get("Retry-After"))
        if retryAfter < 1 {
            retryAfter = 1
        }
        jitter := time.Duration(rand.Intn(500)) * time.Millisecond
        time.Sleep(time.Duration(retryAfter)*time.Second + jitter)
    }
    return nil, fmt.Errorf("rate-limited after retries")
}

​

What counts against the limit

• Successful 2xx responses count.
• 4xx client errors from the endpoint, such as a validation failure or a missing resource, count.
• 5xx server errors count.
• 429 responses count, as described in How the window works.

• Requests that Foil rejects while verifying the key don’t count. These include a missing, malformed, or unrecognized key, a key type or mobile client that isn’t allowed on the path, an origin that isn’t allowed, and an inactive organization.
• Preflight OPTIONS requests don’t count.
• The unauthenticated GET /v2/collect/pings/:pingId and POST /v2/collect/network-checks endpoints don’t count.

​

Reducing your request rate

• Per-request session verification. If you’re calling GET /v1/sessions/:sessionId on every authenticated API hit, you’re doing too much work. Cache the verified sealed token locally (the token already carries the verdict), and only fall back to the sessions API for audits, escalations, or stale sessions. See API abuse → Session reuse.
• Small pages. List endpoints return 50 items per page by default and accept up to 200 with limit. Requesting the largest page your code can process reduces the number of requests by up to a factor of four. The SDK iterators make one request per page, so they don’t reduce request count on their own.
• Unbatched management calls. If you’re provisioning many API keys or organizations, space the calls out with backoff rather than firing them concurrently.
• Polling that could be webhooks. If you poll GET /v1/sessions to find new results, subscribe an endpoint to the session.result.persisted webhook event instead.

​

Raising a limit

• The organization you want raised
• Whether the increase is for publishable keys, secret keys, or both
• Your expected steady-state and peak RPS
• The endpoints you need headroom on

​

What’s next