Usage limits

The HeroUI Agents API enforces the following limits:

The per-Agent limit is shared by every API key that belongs to that Agent. The source-IP limit protects key verification from brute-force and query-exhaustion traffic before a key can be resolved. A request rejected by any limit returns 429 rate_limited with a Retry-After header containing the number of seconds to wait.

Handle rate limits

1. Read the Retry-After header.
2. Wait at least that many seconds.
3. Retry with exponential backoff and jitter if another 429 is returned.
4. Bound the number of retries so a downstream outage cannot create an infinite loop.

Avoid sending simultaneous retries from every worker. Centralized throttling or a queue makes it easier to stay within these limits.

Reduce request volume

• Request up to 100 objects per page when processing complete datasets.
• Follow next_cursor sequentially instead of requesting the same page again.
• Cache immutable results when that fits your data freshness requirements.
• Keep polling intervals conservative, and stop polling when the data is no longer needed.

The public API is read-only. The limits apply across users, conversations, and runs rather than separately to each resource.