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

# Rate limits

> Declare a request rate and HunterAI throttles itself to it. It also backs off on 429.

HunterAI throttles **itself** to a rate you declare, so a sync never floods your API. You
control the ceiling; HunterAI stays under it.

## Declare your rate

When your business owner creates the connection, they set a **rate limit** in requests per
second. HunterAI applies a client-side limiter (a leaky bucket) to every request it makes
to your base URL and never exceeds that rate.

* **Default:** if no rate is set on the connection, HunterAI uses **5 requests per second**.
* The limiter is **per base URL**: all requests to the same API share one budget, so even
  concurrent connections against the same host stay within the declared rate.
* Paging is **sequential** — HunterAI fetches one page, then the next. It does not fan out
  parallel page requests within an entity.

<Tip>
  Pick a rate your API comfortably sustains. There is no benefit to declaring a rate higher
  than your infrastructure can serve; a lower, honest number keeps syncs healthy. Tens of
  requests per second is generous for the data volumes involved.
</Tip>

## Back-pressure with 429

The declared rate is HunterAI's self-imposed ceiling, not a substitute for your own
protection. If you still need to shed load, return [`429`](/errors#429-and-5xx-errors):

* Include a **`Retry-After`** header (in seconds). HunterAI waits at least that long before
  retrying.
* Without `Retry-After`, HunterAI falls back to exponential backoff (`1, 2, 4, 8, 16` s).
* HunterAI retries a throttled request up to **5 times**. If it is still `429` after that,
  the entity fails for this run and resumes from its watermark on the next run.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 10
Content-Type: application/json

{ "error": "rate limit exceeded, retry in 10s" }
```

## Page size

Every request asks for `limit=100`. That is fixed — you cannot make HunterAI request larger
or smaller pages. Size your responses and any per-request cost around 100 records per page.