Skip to main content

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 standard rate-limit headers.
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?

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.
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.