Setup Rate Fast

Implement production-ready API rate limiting with token bucket, sliding window, or fixed window algorithms, Redis-backed storage, tiered user policies, and monitoring integration.

When to Use This Command

Run this command when...

• You need to protect your API endpoints from abuse with configurable rate limits per user, IP, or API key
• You want to implement tiered rate limiting with different quotas for free, premium, and enterprise users
• You need Redis-backed distributed rate limiting that works across multiple application instances
• You want to add specific rate limits to authentication endpoints to prevent brute-force attacks
• You need monitoring and alerting for rate limit violations to detect abuse patterns

Quick Start

Copy
# .claude/commands/setup-rate-fast.yaml
name: Setup Rate Fast
description: Implement API rate limiting with Redis and tiered policies
inputs:
  - name: algorithm
    description: "token-bucket, sliding-window, or fixed-window"
    default: "sliding-window"

Copy
# Setup sliding window rate limiting
claude "setup-rate-fast --algorithm sliding-window"

# Setup with tiered user policies
claude "setup-rate-fast --algorithm token-bucket --tiers free:100,pro:1000,enterprise:10000"

Output:
  [detect] Framework: Express.js
  [install] ioredis, rate-limiter-flexible
  [create] src/middleware/rateLimiter.ts
  [create] src/config/rateLimitPolicies.ts
  [config] Global: 100 req/15min (anonymous)
  [config] Auth endpoints: 5 req/15min
  [config] Tiers: free(100), pro(1000), enterprise(10000)
  [redis] Redis connection configured
  [headers] X-RateLimit-* headers enabled
  Done. Rate limiting active on all routes.

Core Concepts

Concept	Description
Algorithm Selection	Token bucket (burst-friendly), sliding window (smooth), or fixed window (simple) rate limiting
Tiered Policies	Different rate limits per user tier: anonymous, free, pro, enterprise with per-endpoint overrides
Redis Backend	Distributed rate limit state stored in Redis for consistency across multiple app instances
Response Headers	Standard X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every response
Bypass Mechanisms	Whitelist for internal services, health checks, and admin endpoints that should not be rate limited

Rate Limiting Architecture:
  Request ──> IP/Key Extraction ──> Policy Lookup
                                        │
              ┌─────────────────────────┤
              ▼                         ▼
        ┌──────────┐            ┌──────────────┐
        │  Redis   │            │   Algorithm  │
        │  State   │◄──────────>│  (Sliding    │
        │  Store   │            │   Window)    │
        └──────────┘            └──────┬───────┘
                                       │
                            ┌──────────┼──────────┐
                            ▼          ▼          ▼
                       ┌────────┐ ┌────────┐ ┌────────┐
                       │ Allow  │ │ Reject │ │  Log   │
                       │ (200)  │ │ (429)  │ │ Alert  │
                       └────────┘ └────────┘ └────────┘

Configuration

Parameter	Type	Default	Description
algorithm	string	"sliding-window"	Rate limiting algorithm: token-bucket, sliding-window, or fixed-window
tiers	string	"anonymous:100"	Tier definitions: name:limit pairs (comma-separated, per 15-minute window)
redis_url	string	"redis://localhost:6379"	Redis connection URL for distributed state
auth_limit	integer	5	Requests per 15 minutes for authentication endpoints
headers	boolean	true	Include X-RateLimit-* response headers

Best Practices

1. Use sliding window for public APIs -- The sliding window algorithm provides smooth rate limiting without the burst problems of fixed windows, giving a better experience to legitimate users.
2. Set strict limits on auth endpoints -- Login, registration, and password reset endpoints should have much lower limits (5-10 per 15 minutes) than general API endpoints to prevent brute force attacks.
3. Always return rate limit headers -- Clients need X-RateLimit-Remaining to implement backoff logic. Without headers, clients cannot self-regulate and will hit limits unnecessarily.
4. Use Redis for multi-instance deployments -- In-memory rate limiting does not work when your application runs behind a load balancer. Redis ensures consistent limits across all instances.
5. Monitor rate limit violations -- Track 429 responses in your monitoring system. A sudden spike in rate limit violations may indicate an attack or a misconfigured client.

Common Issues

1. Redis not available -- The rate limiter will fail open or crash if Redis is down. Configure a fallback behavior (in-memory limiter or pass-through) for Redis connection failures.
2. Rate limits too aggressive -- Setting limits too low causes legitimate users to get 429 errors. Start with generous limits and tighten them based on observed traffic patterns.
3. API keys not extracted correctly -- The rate limiter needs to identify users by API key, JWT, or IP address. Ensure the key extraction middleware runs before the rate limiter in your middleware chain.