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

# Rate limits for the Lusha API

> Understand the request limits for each Lusha API endpoint group and learn how to implement retry logic for 429 Too Many Requests responses.

The Lusha API enforces rate limits to ensure fair usage and stable performance for all customers. Limits are applied per account, and some are tracked over multiple windows (per second, per minute, per hour, and per day). If your application exceeds a limit, the API returns a `429 Too Many Requests` response.

## Limits by endpoint group

| Endpoint group                                                | Limit                     |
| ------------------------------------------------------------- | ------------------------- |
| All endpoints (default)                                       | 25 requests per second    |
| `GET /account/usage`                                          | 5 requests per minute     |
| Webhooks API (all `/api/subscriptions` and related endpoints) | 100 requests per minute   |
| Create or delete webhook subscriptions                        | 25 items per bulk request |

<Note>
  Rate limits are applied at the account level, not per API key. If multiple systems share the same account, their requests count against the same quota. Higher-tier plans may have higher daily and hourly quotas - contact your account manager if you need a limit increase.
</Note>

## Rate limit response headers

Every response includes headers you can use to track your current usage against each rate limit window:

| Header                   | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `x-rate-limit-minute`    | Total requests allowed per minute on your current plan |
| `x-minute-requests-left` | Requests remaining in the current minute window        |
| `x-minute-usage`         | Requests made in the current minute window             |
| `x-rate-limit-hourly`    | Total requests allowed per hour on your current plan   |
| `x-hourly-requests-left` | Requests remaining in the current hourly window        |
| `x-hourly-usage`         | Requests made in the current hourly window             |
| `x-rate-limit-daily`     | Total requests allowed per day on your current plan    |
| `x-daily-requests-left`  | Requests remaining in the current daily window         |
| `x-daily-usage`          | Requests made in the current daily window              |

<Tip>
  Poll these headers instead of guessing when you are close to a limit - they tell you exactly how much headroom is left in each window.
</Tip>

## 429 Too Many Requests

When you exceed a rate limit, the API returns:

```json theme={null}
{
  "statusCode": 429,
  "message": "Too Many Requests",
  "errors": []
}
```

The `message` reflects which limit was hit - for example, a per-second/per-minute burst, an hourly quota, a daily quota, or a trial account limit. Your client must detect the `429` status code and pause before retrying regardless of the exact message.

## Handling rate limit errors

<Tip>
  Implement exponential backoff with jitter when retrying after a `429`. Start with a short wait (for example, 1 second), double it on each subsequent retry, and add a small random delay to avoid synchronized retries from multiple clients.
</Tip>

A minimal retry pattern looks like this:

```python theme={null}
import time
import random
import requests

def call_with_backoff(url, headers, max_retries=5):
    wait = 1
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        time.sleep(wait + random.uniform(0, 0.5))
        wait *= 2
    return response
```

Additional best practices:

* **Batch requests thoughtfully.** If you need to enrich thousands of records, spread requests over time rather than sending them all at once.
* **Monitor the account usage endpoint sparingly.** Its limit is stricter (5 requests per minute), so poll it infrequently - for example, once at the start of a job rather than before every API call.
* **Distinguish `429` from other errors.** Do not retry `400` or `401` responses; those indicate problems with your request or credentials that retrying will not fix.

## Next steps

If your integration encounters unexpected errors beyond rate limiting, review the full list of [error codes](/error-codes) to understand what each HTTP status code means and how to respond.