API Rate Limiting & Quota Management System

## ROLE

You are a platform infrastructure engineer specializing in API traffic management and abuse prevention at scale. You have designed rate limiting systems that protect APIs serving millions of requests per minute while ensuring legitimate high-volume consumers are not unfairly throttled. You understand the trade-offs between different rate limiting algorithms, the challenges of distributed rate limiting across multiple API server instances, and the business requirements of tiered API plans with different quotas.

## OBJECTIVE

Design and implement a production-grade rate limiting and quota management system for [API NAME] built on [STACK: Node.js + Express / Python + FastAPI / Go + Gin / Java + Spring Boot / .NET / Ruby on Rails]. The API serves [CONSUMER COUNT: hundreds / thousands / tens of thousands] of consumers across [TIER COUNT: 2-5] pricing tiers. The infrastructure runs on [INFRA: single server / multiple servers behind a load balancer / Kubernetes cluster / serverless functions] and traffic peaks at [PEAK: thousands / tens of thousands / hundreds of thousands / millions] of requests per minute. The rate limiting backend uses [BACKEND: Redis / Memcached / in-memory / DynamoDB / custom distributed store].

## TASK: COMPLETE RATE LIMITING SYSTEM DESIGN

### Algorithm Selection & Implementation
Evaluate and implement the rate limiting algorithm best suited to your use case. Analyze each algorithm's behavior, implementation complexity, and memory requirements:

**Fixed Window Counter:** Divide time into fixed windows (e.g., 1-minute intervals), count requests per window, reject when the count exceeds the limit. Advantage: simple, low memory. Disadvantage: burst at window boundaries can allow 2x the rate. Provide the implementation in [STACK] with [BACKEND], including the key schema (ratelimit:{consumer_id}:{window_timestamp}) and atomic increment operations.

**Sliding Window Log:** Store the timestamp of every request, count requests within the trailing window. Advantage: precise, no boundary issues. Disadvantage: high memory usage. Provide the implementation using a sorted set in [BACKEND] with automatic expiry.

**Sliding Window Counter:** Combine the current and previous window counts weighted by the overlap. Advantage: smooth rate enforcement with low memory. Disadvantage: slightly approximate. Provide the implementation that combines fixed window counters with weighted averaging.

**Token Bucket:** Tokens are added at a fixed rate, each request consumes a token, requests are rejected when no tokens remain. Advantage: allows controlled bursts while enforcing average rate. Disadvantage: slightly more complex to implement in distributed systems. Provide the complete implementation including bucket initialization, token refill logic, and atomic consume-and-check operations in [BACKEND].

**Leaky Bucket:** Requests enter a queue that drains at a fixed rate. Advantage: perfectly smooth output rate. Disadvantage: adds latency, complex queue management. Provide the implementation and explain when this is preferred over token bucket.

Recommend the algorithm for your use case with rationale. Provide the complete implementation with [NUMBER: 3-5] code examples covering normal operation, burst handling, and limit exceeded scenarios.

### Tiered Plan Configuration
Define the rate limit structure for each pricing tier. For each tier, specify: requests per second (RPS) limit, requests per minute (RPM) limit, requests per day (RPD) limit, monthly quota, concurrent connection limit, burst allowance (how much the instantaneous rate can exceed the sustained rate), and per-endpoint overrides for expensive operations. Example tier structure:

[TIER 1 NAME: Free / Starter / Developer]: [RPS] req/s, [RPM] req/min, [RPD] req/day, [MONTHLY] req/month, [BURST] burst multiplier.
[TIER 2 NAME: Pro / Growth / Business]: [RPS] req/s, [RPM] req/min, [RPD] req/day, [MONTHLY] req/month, [BURST] burst multiplier.
[TIER 3 NAME: Enterprise / Scale / Unlimited]: Custom limits negotiated per customer.

Design the configuration storage: where tier definitions live (database, config file, environment variables), how limits are loaded (cached in memory with [TTL: 1-5 minute] refresh), and how custom enterprise overrides are managed. Implement per-endpoint rate limiting for expensive operations: [ENDPOINTS: list 3-5 expensive endpoints] have separate, lower limits that apply in addition to the global limits. Provide the complete tier configuration schema and loading mechanism.

### Distributed Rate Limiting Architecture
Design the rate limiting system to work correctly across [SERVER COUNT: 2-50+] API server instances. Address the fundamental challenge: each server sees only a portion of the total traffic, but limits must be enforced globally. Implement centralized rate limiting using [BACKEND]: every API server queries the central store for rate limit decisions. Optimize for latency: pipeline rate limit checks, use connection pooling, and implement a local cache with [CACHE TTL: 100-500ms] to reduce round trips for high-frequency consumers. Handle [BACKEND] failures gracefully: define the failopen vs. failclosed behavior (recommend failopen to avoid blocking all traffic during infrastructure issues, with local per-instance fallback limits at [FALLBACK: 2-5x] the normal rate). Implement eventual consistency handling: when a slight over-limit is acceptable, use local counters that sync to [BACKEND] periodically, reducing backend load by [FACTOR: 5-10x]. Address clock synchronization: how window boundaries are calculated across servers with slightly different clocks. Provide the complete distributed architecture diagram and implementation for your [INFRA].

### Response Headers & Developer Communication
Implement the standard rate limit response headers on every API response, whether the request succeeded or was throttled. Headers: X-RateLimit-Limit (the maximum number of requests allowed in the current window), X-RateLimit-Remaining (the number of requests remaining), X-RateLimit-Reset (the UTC timestamp when the window resets, in Unix epoch seconds), X-RateLimit-Policy (the name of the rate limit policy applied). When a request is throttled, respond with HTTP 429 Too Many Requests. Include the Retry-After header (number of seconds to wait before retrying). Return a JSON error body with the error code, a human-readable message explaining why the request was throttled, the specific limit that was exceeded, the reset time, and a link to documentation about rate limits and how to request a higher tier. Design the rate limit documentation page: explain each tier's limits, describe the headers and their meanings, provide code examples for handling 429 responses with exponential backoff in [NUMBER: 3-5] languages, and document how to check current usage via the API. Implement a usage API endpoint (GET /rate-limit/status) that returns the consumer's current usage across all limit windows, remaining quota, and tier information.

### Monitoring, Alerting & Abuse Detection
Build the monitoring layer. Track metrics: total requests by consumer and tier, requests throttled (429s) by consumer and tier, rate limit utilization percentage (how close each consumer is to their limits), backend latency for rate limit checks, backend failures and failover events, and quota consumption velocity (is a consumer on pace to exhaust their monthly quota early). Design alerts: alert the platform team when global 429 rate exceeds [THRESHOLD: 1-5%], alert when [BACKEND] latency exceeds [LATENCY: 10-50ms], alert when a consumer exceeds [ABUSE THRESHOLD: 10x] their rate limit consistently (possible abuse or misconfigured client). Implement abuse detection patterns: identify consumers making rapid-fire requests that consistently hit the limit, detect distributed abuse attempts from multiple API keys with correlated behavior, and flag consumers making excessive requests to expensive endpoints. Design the response to detected abuse: automated temporary ban after [STRIKES: 3-5] violations within [WINDOW: 1-24 hours], notification to the consumer with details and remediation steps, and manual review queue for the platform team. Provide the complete monitoring configuration for [MONITORING: Prometheus + Grafana / Datadog / CloudWatch / New Relic / custom].