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

# Rate Limits

We limit the number of requests each customer can send. This prevents abuse and keeps the load balanced across all our users.

### Q: How is my rate limit calculated?

* **One budget across the whole API.** All your API requests share a single limit for your environment, whichever endpoints they call. Each endpoint does not have its own limit.
* **Default: 500 requests per minute.** If you need more, contact support and we can raise it for your environment.
* **Rolling window.** We count requests over a sliding one-minute window, not a fixed bucket that resets at the start of each minute. A burst just before and just after the minute boundary doesn't give you two minutes' worth of requests.
* **Dashboard use is separate.** Your team using the Heron dashboard does not count against your API limit.
* **Some endpoints have a stricter limit of their own.**

### Q: How do I know when I'm close to the limit?

Every response carries headers that tell you where you stand:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Requests allowed in the window |
| `X-RateLimit-Remaining` | Requests you have left in the current window |
| `X-RateLimit-Reset` | When the window resets, as a Unix timestamp in seconds |
| `Retry-After` | Seconds to wait before retrying |

Watch `X-RateLimit-Remaining`. Slow down as it gets close to zero, rather than waiting for a 429.

### Q: We are receiving 429 "Too Many Requests" errors. How should we handle them?

A `429` means you went over your limit. The request was not processed, so it is safe to retry.

```json theme={null}
{
	"code": 429,
	"description": "500 per 1 minute",
	"name": "Too Many Requests"
}
```

1. Wait for the number of seconds in the `Retry-After` header, then retry.
2. If you get another 429, back off exponentially (for example 1s, 2s, 4s, 8s, with random jitter added). Never wait less than `Retry-After`.
3. Cap the number of retries, and log any requests you give up on.

Here's a worked code example for retry behaviour:

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

import requests


def request_with_retry(method: str, url: str, max_retries: int = 5, **kwargs) -> requests.Response:
    for attempt in range(max_retries + 1):
        response = requests.request(method, url, **kwargs)
        if response.status_code != 429 or attempt == max_retries:
            return response
        retry_after = int(response.headers.get("Retry-After", 1))
        backoff = 2**attempt + random.random()
        time.sleep(max(retry_after, backoff))
    return response
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.