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

# Rate limits

> Per-token request budget and how to react to 429 responses.

The public API enforces a fixed-window rate limit of **100 requests per minute per API token**. The window resets on the minute boundary advertised in `X-RateLimit-Reset`.

Every response includes:

| Header                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests in the current window (`100`)  |
| `X-RateLimit-Remaining` | Requests left in the current window             |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the window resets |

## When you hit the limit

The API responds with `HTTP 429 Too Many Requests` and a body like:

```json theme={null}
{ "statusCode": 429, "message": "Rate limit exceeded" }
```

Wait until `X-RateLimit-Reset` and retry. Implement exponential backoff if you are issuing bursts.

## Designing for the limit

* **Pre-aggregate**: when syncing many records, prefer a smaller number of larger requests over many small ones. Most resources support cursor pagination; use the largest page size that fits your schema.
* **Spread retries**: if your integration retries on transient errors, add jitter to avoid creating self-inflicted thundering herds.
* **Issue purpose-scoped tokens**: each token has its own budget, so a webhook listener and a backfill job on separate tokens won't starve each other.

If you need higher throughput, contact us — bulk endpoints and elevated limits are available on request.