Usage limits

The HeroUI Agents API enforces the following limits:

The per-key limit is workspace-wide, while the per-Agent limit is shared by every workspace key targeting that Agent. Adding Agents cannot multiply a key's allowance. The source-IP limit protects key verification before a key can be resolved. A rejected request 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.
• Poll a processing knowledge document with exponential backoff, then stop when status becomes ready or failed.

The limits apply across users, conversations, runs, and knowledge operations rather than separately to each resource.