rate-limiting

name	rate-limiting
description	Use when: protect a service with rate limiting and backpressure without harming legitimate users.

Goal: limit abuse and overload while staying fair to real traffic.

Use for:

• protecting APIs and expensive endpoints
• preventing abuse, scraping, and accidental floods
• shaping traffic to downstream capacity

Workflow:

1. Pick the dimension: per IP, per user, per API key.
2. Choose an algorithm: token bucket, sliding window, or leaky bucket.
3. Set limits from real capacity and usage patterns.
4. Return 429 with Retry-After and clear limit headers.
5. Apply backpressure and timeouts to protect dependencies.
6. Monitor rejection rates and adjust thresholds.

Patterns:

• token bucket for bursts with a steady refill
• sliding window for smooth enforcement
• distributed counter (e.g. Redis) for multi-instance limits
• separate limits for anonymous vs. authenticated

Rules:

• always return 429 with Retry-After, not a silent drop
• key limits on a stable identity, not just IP when possible
• fail closed on critical resources, open on best-effort ones
• expose remaining-quota headers so clients can adapt