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

# Rate Limiting

> How Frost Auth limits request volume, what the thresholds are, and what to do when you hit them.

### What is rate limiting?

Rate limiting controls how many requests a single source can make within a given time window. It protects the service from abuse, keeps latency stable for everyone, and catches accidental retry loops before they cascade.

### Why does Frost Auth rate limit?

Frost Auth serves every activation, heartbeat, and panel request from shared infrastructure. Without limits, one misbehaving client in a tight loop could degrade the service for thousands of other developers. Rate limiting also protects your own users; a brute-force attempt against a panel login is throttled long before it becomes a threat.

### What are the limits?

Every limit answers HTTP `429` with the `errorCode` `RATE_LIMITED` and carries [draft-7](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) standard rate-limit headers.

| Route | Window | Limit | Keyed by |
| - | - | - | - |
| `POST /api/v1/activate` | 1 min | 20 | IP |
| `POST /api/v1/validate` | 1 min | 60 | IP |
| `GET /api/v1/settings/catalog/:owner/:app` | 1 min | 60 | IP |
| `POST /api/v1/panel/…/login` | 15 min | 15 | IP |
| Panel session writes | 1 min | 10 | Account |
| `POST /api/v1/auth/login` · `register` | 15 min | 20 | IP |
| `POST /api/v1/auth/2fa/*` | 1 min | 10 | Account |

> [!NOTE]
>
> IP limits and account limits are independent. A single host spraying many accounts and many hosts hitting one account are both caught, they count separately.

### What does the response look like?

```json theme={null}
{
  "error": true,
  "response": {
    "code": 429,
    "message": "Too many requests",
    "errorCode": "RATE_LIMITED"
  }
}
```

The response also includes draft-7 headers (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`) telling you exactly when the window clears. Read `RateLimit-Reset` and wait — do not poll.

### Brute-force backoff

On top of the counters, failed sign-ins and failed two-factor codes trigger a per-identity escalating lockout:

* **5 free attempts** before any delay.
* After that, a **doubling backoff** starting at 2 seconds, escalating up to **15 minutes**.
* Counted against the **account** and the **source address** separately.

This is not a rate limit you can wait out in seconds. If you're locked out after repeated wrong passwords, the lockout grows exponentially with each additional failure.

### How is my IP determined?

The client IP is resolved in this order:

1. `cf-connecting-ip` header (Cloudflare edge)
2. `x-forwarded-for` header
3. Socket peer address

If you're behind a proxy or load balancer, make sure it forwards the real client IP — otherwise all your users share one limit bucket.

### How do I avoid hitting limits?

* **Heartbeat correctly.** Beat every `heartbeatSeconds` returned in the activation response. Beating faster is allowed but buys nothing — writes are throttled server-side to one per window anyway.
* **Don't retry on 429.** Read the `RateLimit-Reset` header and schedule your next attempt after it. Immediate retries just extend the lockout.
* **Batch where possible.** If you're generating licenses or managing users from a script, pace your calls rather than firing them in a tight loop.
* **Use session tokens.** After activation, heartbeat with `session.token` instead of re-sending the key. The token form is lighter and doesn't re-trigger key-based validation paths.

### I'm rate limited. Now what?

Wait for the window to clear. The `RateLimit-Reset` header tells you the exact second. For activation and validate, that's at most 60 seconds. For login routes, at most 15 minutes.

If you're hitting limits during normal operation (not a bug or retry loop), your usage pattern may exceed what the current thresholds allow. Contact support — limits can be reviewed for legitimate high-volume integrations.

> [!WARNING]
>
> There is no way to bypass a rate limit from the client side. Switching IPs, adding headers, or retrying faster will not help. The limits are enforced server-side and shared across all instances.


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