> Markdown version of https://authpi.com/docs/reference/rate-limits/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Rate limits

Learn more about rate limits for our APIs and how to handle them.

AuthPI rate-limits traffic at the network edge: requests to both the Core API and the IdP API are evaluated by our edge layer (Cloudflare) before they reach the application.

## How it works

- Limits are enforced **per client IP and endpoint class** at the edge, in front of both APIs.
- Exact thresholds are **operational settings** — we tune them over time and they are not part of the API contract. Build your client against the behavior described below rather than against specific numbers.
- When a limit is exceeded, the edge responds with `429 Too Many Requests` without the request reaching the API.

## Handling 429s

- A `429` response includes a `Retry-After` header (in seconds) when available — wait at least that long before retrying.
- Because the response is generated at the edge, it may not use the API's standard JSON error envelope. **Handle rate limiting by status code, not by response body shape.**
- The official admin SDKs (TypeScript and Python) automatically retry safe requests (`GET`, `HEAD`, `OPTIONS`) on `429` and honor `Retry-After`. Mutations (`POST`, `PATCH`, `DELETE`) are never retried automatically — use idempotency keys and retry explicitly.

## Built-in throttling on authentication flows

Separately from edge rate limits, authentication flows have their own attempt throttling: repeated failed verification attempts (passwords, one-time codes, MFA) temporarily lock the credential — 5 failed attempts trigger a 15-minute lockout. These protections return flow-specific errors, not `429`.

## Best practices

To avoid hitting rate limits, consider the following best practices:

- **Use caching**: Cache responses where possible to reduce the number of requests made to the API.
- **Implement exponential backoff**: If you receive a `429 Too Many Requests` response, implement an exponential backoff strategy to retry the request after waiting for the specified time.
- **Monitor usage**: Keep track of your API usage and adjust your application logic to avoid exceeding the rate limits.
- **Contact support**: If you consistently hit rate limits and need higher limits, consider reaching out to our support team for assistance.