Rate Limiting

Why per-request counts

Most attacks aren't one big request — they're hundreds or thousands. Brute-forcing a login, scraping a product catalog, enumerating user IDs all generate spike patterns that look nothing like a real user's. Rate limiting catches them by counting requests per identity and blocking when the count exceeds a budget.

Identity keys

Each rate limit rule picks an identity to count by:

• IP — most basic. Effective against single-source attacks.
• IP + path — different budgets per endpoint. Most common setting.
• User ID (from cookie/JWT) — per-user, even from multiple devices.
• API key — if your endpoint authenticates via API key.
• Custom header — e.g. X-Tenant-ID for multi-tenant SaaS.

Algorithm

Sliding window counters with 1-second resolution. Each identity key + rule maintains a circular buffer in Cloudflare KV; on every request, Shield reads the buffer, sums the last N seconds, and compares to the budget.

Cheaper than a true token-bucket but precise enough for the typical use cases. Decision time at the edge: 1-3ms.

Common rules to deploy

# Login brute-force protection
identity: IP
path: /login OR /auth/*
budget: 5 requests / 60 seconds
action: Block + 5-minute deny

# Signup farming
identity: IP
path: /signup OR /register
budget: 3 requests / 60 seconds
action: Challenge

# API per-key fair-use
identity: api_key
path: /api/*
budget: 1000 requests / 60 seconds
action: 429 with Retry-After

# Per-user expensive endpoint
identity: user_id from cookie
path: /api/v1/reports/generate
budget: 10 / hour
action: 429 with reset time

Actions

• Block — 429 Too Many Requests, no body.
• Block + add to deny list — escalation; subsequent requests from this IP get the IP Access deny treatment for N minutes.
• Challenge — Turnstile challenge before allowing.
• 429 with Retry-After — graceful response with reset time. Use for API rate limits where you want clients to back off cleanly.
• Log only — no enforcement, just count. For tuning.

Whitelist / exemptions

Per-rule whitelist by IP, ASN, or User-Agent. Useful for:

• Internal monitoring + load testing.
• Partner integrations that legitimately hit your endpoint at high rates.
• Your own scrapers / batch jobs.

Tuning

Run in Log mode for a week. The analytics dashboard shows the 99th-percentile request count per identity per minute for each endpoint — that's your floor for budget setting. Budget = 99p × 2 typically catches abusers without breaking real users.

What's next

• IP Access — escalation target for rate-limit violators.
• Managed Rulesets — credential-stuffing patterns that complement rate limiting.