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

# Rate limits

> Where HQ throttles requests, and how to handle a 429.

HQ rate-limits its most abuse-sensitive endpoints **per client IP**. Exceed a limit and you get `429 Too Many Requests`; back off and retry.

## OAuth endpoints

The OAuth endpoints — `/v1/oauth/authorize`, `/v1/oauth/token`, `/v1/oauth/introspect`, `/v1/oauth/revoke` — allow a **burst of 30 requests**, then refill at **1 request per second**, keyed on the caller's IP. That's well above a normal sign-in or token-refresh cadence; it only bites credential-stuffing-style bursts.

## Handling a 429

* Treat `429` as transient: retry with **exponential backoff and jitter**.
* Don't hammer the token endpoint — refresh an access token shortly **before** it expires (\~1 hour), not on every request.
* The limiter is IP-keyed, so all of one backend's calls share a bucket; spread bursty traffic out.

<Note>Most data endpoints aren't IP-rate-limited today, but treat any `429` as a signal to back off — limits can tighten as the API grows.</Note>