---
updatedAt: 2026-09-08T13:38:19.000Z
agentTools:
  projectIndex: https://docs.cognism.com/llms.txt
---

# Rate Limits

How Cognism API rate limits work, how to read the RateLimit-* headers, and how to handle 429 responses gracefully.

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

| Operation    | Routes                                                       | Limit                 |
| :----------- | :----------------------------------------------------------- | :-------------------- |
| `search`     | `POST /persons/filter`, `POST /companies/filter`             | 500 requests / minute |
| `count`      | `POST /persons/filter/count`, `POST /companies/filter/count` | 500 requests / minute |
| `dictionary` | `GET /dictionaries/*`                                        | 500 requests / minute |

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

<Callout icon="📘" theme="info">
  Rate limits govern request frequency only. Record volume is governed separately by [search tokens](/docs/credits-and-search-tokens); running out of tokens returns `402`, not `429`.
</Callout>

## 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.

| Header                | Meaning                                                                  | Present on     |
| :-------------------- | :----------------------------------------------------------------------- | :------------- |
| `RateLimit-Limit`     | Requests allowed in the window                                           | Every response |
| `RateLimit-Remaining` | Requests left in the current window                                      | Every response |
| `RateLimit-Reset`     | Seconds until the window resets                                          | Every response |
| `RateLimit-Policy`    | The policy in force, e.g. `500;w=60` (500 requests per 60-second window) | Every response |
| `Retry-After`         | Seconds to wait before retrying                                          | `429` only     |

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
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 500
RateLimit-Remaining: 0
RateLimit-Reset: 34
RateLimit-Policy: 500;w=60
Retry-After: 34
```

```json
{
  "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

```javascript
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.

```text
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.