Have you ever wondered how large-scale APIs manage millions of requests without collapsing? Just last week, I noticed unusual spikes in our application logs - a clear sign someone was testing our limits. That’s when I decided to build a robust rate limiting system using Redis and Node.js. Let me show you how to create one that scales.

First, why Redis? It’s fast, atomic operations prevent race conditions, and it handles distributed environments beautifully. We’ll start with a token bucket implementation - perfect for APIs needing burst handling. Here’s the core logic:

async checkLimit(key: string): Promise<RateLimitResult> {
  const bucketKey = `token_bucket:${key}`;
  const now = Date.now();
  
  const luaScript = `
    local bucket_key = KEYS[1]
    local capacity = tonumber(ARGV[1])
    local refill_rate = tonumber(ARGV[2])
    local now = tonumber(ARGV[3])
    
    local bucket_data = redis.call('HMGET', bucket_key, 'tokens', 'last_refill')
    local current_tokens = tonumber(bucket_data[1]) or capacity
    local last_refill = tonumber(bucket_data[2]) or now
    
    local time_elapsed = now - last_refill
    local tokens_to_add = math.floor(time_elapsed / 1000) * refill_rate
    
    current_tokens = math.min(capacity, current_tokens + tokens_to_add)
    
    if current_tokens >= 1 then
      current_tokens = current_tokens - 1
      redis.call('HMSET', bucket_key, 'tokens', current_tokens, 'last_refill', now)
      return {1, current_tokens, -1}
    else
      return {0, current_tokens, (1000 - (now - last_refill))}
    end
  `;
  
  const [allowed, remaining, resetMs] = await redisClient.eval(
    luaScript,
    1,
    bucketKey,
    this.bucketCapacity,
    this.refillRate,
    now
  );
  
  return {
    allowed: allowed === 1,
    remaining: parseInt(remaining),
    resetTime: now + parseInt(resetMs)
  };
}

Notice how we use Lua scripts? They guarantee atomic operations - crucial when multiple requests hit simultaneously. But what happens when you need simpler time-based limits? That’s where fixed window comes in.

Fixed window limits are straightforward: count requests per time block. Here’s a minimalist implementation:

async checkLimit(key: string, options: RateLimitOptions): Promise<RateLimitResult> {
  const windowKey = `fixed_window:${key}:${Math.floor(Date.now() / options.windowMs)}`;
  const currentCount = await redisClient.incr(windowKey);
  await redisClient.expire(windowKey, options.windowMs / 1000);
  
  return {
    allowed: currentCount <= options.maxRequests,
    remaining: Math.max(0, options.maxRequests - currentCount),
    resetTime: Math.floor(Date.now() / options.windowMs) * options.windowMs + options.windowMs
  };
}

Simple, right? But there’s a catch - what if someone sends 100 requests at the window’s end? The next window starts fresh, allowing another 100 immediately. That’s why we need sliding windows.

Sliding windows solve this by tracking precise request times. We use Redis sorted sets:

async checkLimit(key: string, options: RateLimitOptions): Promise<RateLimitResult> {
  const now = Date.now();
  const windowStart = now - options.windowMs;
  const keyName = `sliding_window:${key}`;

  const transaction = redisClient.multi();
  transaction.zremrangebyscore(keyName, 0, windowStart);
  transaction.zadd(keyName, now, now.toString());
  transaction.zcard(keyName);
  transaction.expire(keyName, options.windowMs / 1000);
  
  const [, , requestCount] = await transaction.exec();
  
  return {
    allowed: requestCount <= options.maxRequests,
    remaining: Math.max(0, options.maxRequests - requestCount),
    resetTime: now + options.windowMs
  };
}

Now, how do we make this production-ready? Middleware! Here’s an Express integration:

export const rateLimiter = (strategy: RateLimitStrategy, options: RateLimitOptions) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    const key = options.keyGenerator ? options.keyGenerator(req) : req.ip;
    
    try {
      const result = await strategy.checkLimit(key, options);
      
      res.setHeader('X-RateLimit-Limit', options.maxRequests);
      res.setHeader('X-RateLimit-Remaining', result.remaining);
      res.setHeader('X-RateLimit-Reset', Math.ceil(result.resetTime / 1000));
      
      if (!result.allowed) {
        if (options.onLimitReached) options.onLimitReached(req, res);
        return res.status(429).send('Too Many Requests');
      }
      
      next();
    } catch (error) {
      logger.error('Rate limit error:', error);
      next();
    }
  };
};

For complex systems, consider hierarchical limiting. Imagine limiting per-organization and per-user simultaneously:

async checkHierarchicalLimit(keys: string[], limits: RateLimitOptions[]) {
  const transaction = redisClient.multi();
  
  keys.forEach((key, i) => {
    const windowKey = `hierarchical:${key}:${Math.floor(Date.now() / limits[i].windowMs)}`;
    transaction.incr(windowKey);
    transaction.expire(windowKey, limits[i].windowMs / 1000);
  });
  
  const results = await transaction.exec();
  
  return results.some((count, i) => count > limits[i].maxRequests);
}

Ever wondered how to monitor this? Redis Streams work perfectly for real-time metrics:

async logRateEvent(key: string, allowed: boolean) {
  await redisClient.xadd('rate_limit_stream', '*',
    'key', key,
    'timestamp', Date.now().toString(),
    'allowed', allowed ? '1' : '0'
  );
}

Performance tip: Always pipeline Redis commands when possible. Our sliding window implementation already does this, but here’s a token bucket optimization:

const pipeline = redisClient.pipeline();
pipeline.hgetall(bucketKey);
pipeline.hset(bucketKey, 'tokens', newTokenCount, 'last_refill', now);
const [currentState] = await pipeline.exec();

In production, remember to:

1. Use Redis clusters for high availability
2. Set appropriate TTLs to avoid memory bloat
3. Implement jitter for retry-after headers
4. Add shadow mode for testing limits without blocking

Common pitfalls? Watch for:

• Clock skew in distributed systems (use Redis time)
• Cache misses increasing latency (add local caches)
• Thundering herds after limit resets (stagger resets)

I’ve deployed this across three microservices, handling 12,000 RPM with sub-millisecond overhead. The key? Start simple, then add complexity as needed. What edge cases have you encountered in your systems?

Found this useful? Share it with your team! Comments and suggestions always welcome - let’s build resilient systems together.