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

# Rate limits

> Per-API-key request limits, what a 429 looks like, and how to stay under the limits

Requests are rate-limited **per API key** over a rolling **one-minute window**. The limit that applies depends on what the request does:

| Tier       | Applies to                          | Limit            |
| ---------- | ----------------------------------- | ---------------- |
| Reads      | All `GET` requests                  | **300 / minute** |
| Mutations  | `POST`, `PATCH`, `DELETE`           | **60 / minute**  |
| OTP resend | `PATCH /request/resend/{requestId}` | **20 / minute**  |

The tier is selected automatically from the request — reads and mutations don't share a bucket, so heavy polling doesn't starve your writes (or vice versa).

## When you exceed a limit

The API responds with `429 Too Many Requests`:

```json theme={"dark"}
{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}
```

Nothing is queued — the request was not processed. Retry after backing off; the window is one minute, so a short exponential backoff (for example 1s → 2s → 4s, capped at 30s) recovers quickly.

## Staying under the limits

* **Prefer webhooks over polling.** Every request outcome is pushed to your [webhook endpoint](/essentials/webhooks-intro); a poll loop against `GET /request/{id}` spends read budget to learn what a webhook would have told you immediately.
* **Page deliberately.** List endpoints accept `pageSize` up to 100 — one page of 100 costs a single read, not ten pages of 10.
* **Treat the resend limit as a safety rail.** `PATCH /request/resend` delivers a new OTP to a real person; 20/minute is deliberately tight to protect recipients from notification storms.
* **One key per integration.** Limits are per key, so separate workloads (e.g. a backend service and an internal script) don't compete if they use their own keys.

Limits may be tuned over time; treat the numbers above as the current defaults rather than a contract. If your integration legitimately needs more, contact us.