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

# Rate Limits

> Throttling for API routes (API key)

## Limits

API routes (`/api/v1/...`) are rate-limited **per API key** (after successful authentication).

Default (current implementation): **60 requests per minute** per key. Limits may change; check response headers.

## Headers

On rate-limited responses (`429`), **`error.code`** is **429**. The JSON body may include **`error.details.retryAfterSeconds`**.

Headers:

* `Retry-After` — seconds to wait before retrying
* `X-RateLimit-Limit` — max requests in the window
* `X-RateLimit-Remaining` — remaining in the current window
* `X-RateLimit-Reset` — epoch ms when the window resets
* `X-Request-Id` — same as `error.request_id` when present

## Best practices

* Use exponential backoff when you receive `429`.
* Cache list results when possible instead of polling aggressively.
* Run integrations from a server, not from end-user devices.