Rate Limits

Rate limits are your request allowance: how many calls you can make in a window, independent of how many records those calls return. They protect the platform for every customer and are enforced per account, per operation, in a fixed 60-second window.

Limits by operation

Because each operation has its own window, saturating search does not lock you out of count or the dictionaries. Health probes are never limited.

Response headers

Every rate-limited response carries the IETF standard rate-limit headers, so you can monitor usage and throttle before you hit the limit.

If the limiter's backing store is temporarily unavailable, requests are allowed through and the RateLimit-* headers are omitted. Absent headers mean "unknown", not "unlimited" — keep your client throttling on its own schedule.

Handling a 429

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 500
RateLimit-Remaining: 0
RateLimit-Reset: 34
RateLimit-Policy: 500;w=60
Retry-After: 34

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded for operation 'search'. Retry after 34 seconds.",
  "operation": "search",
  "window": "sustained",
  "retryAfter": 34
}

1. Read operation to see which class of request was throttled. The other operations may still have capacity.
2. Wait Retry-After seconds. It is never longer than the window (60 seconds), so a short sleep is the correct response.
3. Add jitter if you run parallel workers, so they do not all resume on the same tick and immediately trip the limit again.

Example retry logic

async function callWithRetry(fn, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const response = await fn();
    if (response.status !== 429) return response;

    const retryAfter = Number(response.headers.get("Retry-After") ?? 1);
    const jitterMs = Math.random() * 500;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitterMs));
  }
  throw new Error("Rate limit retries exhausted");
}

Throttle proactively

Rather than waiting for a 429, read RateLimit-Remaining on every response and slow down as it approaches zero. Spreading requests evenly across the minute is more reliable than bursting and backing off.

RateLimit-Remaining: 40   → fine
RateLimit-Remaining: 5    → pause until RateLimit-Reset

Requesting a higher limit

Limits are set per subscription package. If your integration needs sustained throughput above 500 requests per minute for an operation, contact your Cognism account team.