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

# Rate limits

> How v2 rate limits work, the X-RateLimit-* headers on API responses, and how to back off on 429.

The v2 API enforces rate limits **per team**. Before a request is authenticated (when the key can't yet be resolved to a team), the limiter falls back to per-IP.

## Response headers

Most v2 API responses, whether 2xx or not, carry three headers. The unauthenticated `/v2/openapi.json` document is an exception.

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | The window's total budget. |
| `X-RateLimit-Remaining` | How many requests you have left in the current window. |
| `X-RateLimit-Reset` | Seconds until the window resets and the budget refills. |

Use `X-RateLimit-Remaining` to pace yourself proactively — dropping to `0` triggers `429` on the next call.

## Handling `429`

When you exceed the budget, v2 answers `429 Too Many Requests` with the shared [error envelope](/docs/api-reference/v2/errors) and a `Retry-After: <seconds>` header:

```http theme={null}
HTTP/1.1 429 Too Many Requests
X-Request-Id: req_01J9C2VZH8...
Retry-After: 5
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 5

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 5 seconds."
  },
  "requestId": "req_01J9C2VZH8..."
}
```

Wait at least `Retry-After` seconds before retrying. In practice, back off exponentially with jitter and cap the wait at a few minutes.

```ts theme={null}
async function fetchWithBackoff(input: RequestInfo, init: RequestInit) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(input, init);
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
    const jitter = Math.random() * 250;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error("Rate-limited after 5 attempts");
}
```

<Note>
  `/v2/openapi.json` is not rate-limited — the OpenAPI document is static and safe to fetch freely.
</Note>


## Related topics

- [PickFu REST API reference and conventions](/docs/api-reference/introduction.md)
- [Errors](/docs/api-reference/v2/errors.md)
- [PickFu API v2](/docs/api-reference/v2/introduction.md)
- [List survey exports](/docs/api-reference/surveys/list-survey-exports.md)
- [PickFu CLI for surveys and automation](/docs/integrations/cli.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.