Rate limits

The Kua API applies fair-use rate limits to keep the platform responsive for everyone. Your integration must handle throttling during normal requests, retries and concurrent work; this guide does not promise a fixed account-wide quota.

When you’re limited

A throttled request returns HTTP 429 Too Many Requests with the standard error body. Back off and retry — the limit is a short rolling window, so wait before retrying; honour Retry-After if the response supplies it. Do not assume every route uses the same budget.

Handling it gracefully

• Back off exponentially. On a 429, wait a moment and retry, increasing the delay each attempt (e.g. 1s, 2s, 4s) with a little random jitter.
• Prefer webhooks over polling. If you’re calling /v1/events in a tight loop to react to changes, register a webhook instead — Kua pushes events to you, so you make far fewer requests.
• Batch where you can. Page with a larger limit rather than many small requests.

Need a higher limit?

If your integration has a legitimate need for more headroom, reach out at engineering@kuahr.com and we’ll work with you.

Recovery-specific limits

Webhook replay has explicit limits of three replays per delivery per 24 hours and 100 per endpoint per hour. Its 429 is a recovery budget, not an invitation to generate new request keys or endpoints. Preserve the original request key/reason and follow recovery.

Done when: your client bounds retries, adds jitter, avoids tight empty-result polling and keeps uncertain writes for reconciliation. Continue with errors and go-live readiness.