> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naturalead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Global and per-API rate limiting tiers, headers, and best practices

# Rate Limits

Naturalead enforces multiple rate limiting tiers to ensure fair usage and platform stability. All rate limits use a **sliding window** of 60 seconds.

## Rate limit tiers

| Tier        | Limit         | Scope          | Applied To                                               |
| ----------- | ------------- | -------------- | -------------------------------------------------------- |
| **Global**  | 1,000 req/min | Per IP address | All requests                                             |
| **API Key** | 500 req/min   | Per API key    | Requests authenticated with an API key                   |
| **Sync**    | 50 req/min    | Per API key    | `POST /api/leads/sync` and `DELETE /api/leads/sync` only |
| **Account** | 2,000 req/min | Per account    | All authenticated requests for an account                |

### How tiers stack

A single request may count against multiple tiers simultaneously:

1. **Global** — always applies (based on IP)
2. **API Key** — applies when using API key auth
3. **Sync** — applies only to lead sync endpoints (in addition to API key limit)
4. **Account** — applies when account is resolved (bounds total across all keys)

<Info>
  The account limit (2,000/min) bounds total traffic regardless of how many API keys exist. Even if you have 10 keys, each at 500/min, the account total cannot exceed 2,000/min.
</Info>

## Response headers

All responses include rate limit headers following the [IETF draft-7](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) standard:

| Header                | Description                                   | Example |
| --------------------- | --------------------------------------------- | ------- |
| `RateLimit-Limit`     | Maximum requests allowed in the window        | `1000`  |
| `RateLimit-Remaining` | Requests remaining in the current window      | `742`   |
| `RateLimit-Reset`     | Seconds until the window resets               | `34`    |
| `Retry-After`         | Seconds to wait before retrying (only on 429) | `12`    |

## Rate limit exceeded response

When a rate limit is exceeded, the API returns `429 Too Many Requests`:

```json theme={null}
{
  "error": "Too many requests, please try again later"
}
```

The specific error message varies by tier:

| Tier    | Error Message                                                           |
| ------- | ----------------------------------------------------------------------- |
| Global  | `"Too many requests, please try again later"`                           |
| API Key | `"API key rate limit exceeded, please try again later"`                 |
| Sync    | `"Sync API rate limit exceeded. Maximum 50 batch requests per minute."` |
| Account | `"Account rate limit exceeded, please try again later"`                 |

## Best practices

### Implement exponential backoff

When you receive a `429`, wait for the `Retry-After` header value before retrying:

<CodeGroup>
  ```python Python theme={null}
  import time
  import requests

  def api_call_with_retry(url, headers, max_retries=3):
      for attempt in range(max_retries):
          response = requests.get(url, headers=headers)

          if response.status_code == 429:
              retry_after = int(response.headers.get("Retry-After", 5))
              time.sleep(retry_after)
              continue

          return response

      raise Exception("Max retries exceeded")
  ```

  ```javascript Node.js theme={null}
  async function apiCallWithRetry(url, headers, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      const response = await fetch(url, { headers });

      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get("Retry-After") || "5");
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      return response;
    }

    throw new Error("Max retries exceeded");
  }
  ```
</CodeGroup>

### Monitor your usage

Check `RateLimit-Remaining` headers proactively to throttle before hitting limits.

### Use bulk endpoints

For lead management, prefer the [Lead Sync](/api-reference/lead-sync/bulk-sync) endpoint over individual creates. One sync request can process multiple leads, using only one count against the rate limit.

### Spread requests evenly

Avoid bursting all requests at once. Distribute API calls evenly across the 60-second window for best throughput.