Rate limiting

Rate Limiting

Statfyr includes built-in per-IP rate limiting to protect your server from excessive API traffic.

---

How It Works

When rate limiting is enabled, Statfyr tracks how many requests each IP address makes within a sliding time window. If an IP exceeds the configured limit, subsequent requests are rejected until the window resets.

• Tracking is per IP address
• The window is sliding, not fixed
• Limits apply to all endpoints equally

---

Configuration

security:
  enable-rate-limit: true
  rate-limit-requests: 120
  rate-limit-window-seconds: 60

Key	Default	Description
enable-rate-limit	true	Enable or disable rate limiting entirely
rate-limit-requests	120	Maximum requests allowed within the window
rate-limit-window-seconds	60	Duration of the rate limit window in seconds

The default allows 120 requests per minute per IP — sufficient for dashboards, bots, and integrations under normal load.

---

When the Limit Is Exceeded

The API returns:

HTTP/1.1 429 Too Many Requests

{
  "success": false,
  "status": 429,
  "error": "Too Many Requests"
}

---

Tuning Recommendations

Use Case	Suggested Config
Public API, open access	120 req / 60s (default)
Private dashboard, single client	300 req / 60s
Bot polling leaderboards frequently	60 req / 10s
High-traffic public leaderboard	Pair with IP whitelist instead

---

Disabling Rate Limiting

If you are using an IP whitelist or another external rate limiter (e.g. Nginx, Cloudflare), you can disable Statfyr's built-in limiting:

security:
  enable-rate-limit: false

Caution: Disabling rate limiting on a publicly exposed API without any other protection can allow abuse.

---

Next: Caching