HunterAI throttles itself to a rate you declare, so a sync never floods your API. You
control the ceiling.
Declare your rate
When your business owner creates the connection, they set a rate limit in requests per
second. HunterAI applies a client-side rate limiter to every request it makes on that
connection.
- Default: if no rate is set on the connection, HunterAI uses 5 requests per second.
- The limiter is per connection: each connection gets its own budget, so two
connections against the same base URL are throttled independently and the traffic they
send you adds up.
- Paging is sequential — HunterAI fetches one page, then the next. It does not fan out
parallel page requests within an entity.
Treat the declared rate as a target rather than a hard ceiling. Sustained load may
reach a small multiple of it — size with headroom. If you need a firm limit, enforce it
yourself with 429. 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.
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:
- 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.
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. 
