API Rate Limiting Patterns

Rate limiting protects your API from abuse, prevents cascading failures, and enforces fair usage tiers. This guide covers all four algorithms, Redis implementations you can copy directly, Nginx configuration, and the response headers your clients need to back off gracefully.

Algorithm Comparison

Redis: Fixed Window (INCR + EXPIRE)

// Node.js — fixed window rate limiter
import { createClient } from 'redis';

const redis = createClient();
await redis.connect();

async function fixedWindowRateLimit(
  userId: string,
  limitPerMinute: number
): Promise{{ allowed: boolean; remaining: number; resetIn: number }} {
  const windowSeconds = 60;
  const now = Math.floor(Date.now() / 1000);
  const windowStart = Math.floor(now / windowSeconds) * windowSeconds;
  const key = `rate:fixed:${userId}:${windowStart}`;

  const count = await redis.incr(key);

  if (count === 1) {
    // First request in this window — set expiry
    await redis.expire(key, windowSeconds);
  }

  const resetIn = windowStart + windowSeconds - now;

  return {
    allowed: count <= limitPerMinute,
    remaining: Math.max(0, limitPerMinute - count),
    resetIn,
  };
}

Redis: Sliding Window Counter (Lua — Atomic)

-- sliding_window.lua
-- KEYS[1]: current window key   e.g. rate:user:42:1704067200
-- KEYS[2]: previous window key  e.g. rate:user:42:1704067140
-- ARGV[1]: current timestamp (seconds)
-- ARGV[2]: window size in seconds
-- ARGV[3]: max requests per window
-- Returns: { allowed (0|1), current_count, remaining }

local currentKey  = KEYS[1]
local previousKey = KEYS[2]
local now         = tonumber(ARGV[1])
local windowSize  = tonumber(ARGV[2])
local limit       = tonumber(ARGV[3])

local currentCount  = tonumber(redis.call('GET', currentKey) or 0)
local previousCount = tonumber(redis.call('GET', previousKey) or 0)

-- Weight of previous window within the sliding window
local windowStart  = math.floor(now / windowSize) * windowSize
local elapsed      = now - windowStart
local prevWeight   = 1 - (elapsed / windowSize)

local estimatedCount = currentCount + math.floor(previousCount * prevWeight)

if estimatedCount >= limit then
  return { 0, estimatedCount, 0 }
end

-- Increment current window
local newCount = redis.call('INCR', currentKey)
if newCount == 1 then
  redis.call('EXPIRE', currentKey, windowSize * 2)
end

local remaining = limit - estimatedCount - 1
return { 1, estimatedCount + 1, remaining }

// Node.js — call the Lua script
const slidingWindowScript = fs.readFileSync('./sliding_window.lua', 'utf8');

async function slidingWindowRateLimit(userId: string, limit: number) {
  const windowSize = 60; // 1 minute
  const now = Math.floor(Date.now() / 1000);
  const currentWindow  = Math.floor(now / windowSize) * windowSize;
  const previousWindow = currentWindow - windowSize;

  const result = await redis.eval(slidingWindowScript, {
    keys: [
      `rate:sw:${userId}:${currentWindow}`,
      `rate:sw:${userId}:${previousWindow}`,
    ],
    arguments: [String(now), String(windowSize), String(limit)],
  }) as [number, number, number];

  return {
    allowed:   result[0] === 1,
    count:     result[1],
    remaining: result[2],
    resetAt:   currentWindow + windowSize,
  };
}

Token Bucket with Redis

-- token_bucket.lua
-- KEYS[1]: bucket key
-- ARGV[1]: current timestamp (ms float)
-- ARGV[2]: bucket capacity (max tokens)
-- ARGV[3]: refill rate (tokens per second)
-- ARGV[4]: tokens to consume (default 1)

local key      = KEYS[1]
local now      = tonumber(ARGV[1])
local capacity = tonumber(ARGV[2])
local rate     = tonumber(ARGV[3])
local consume  = tonumber(ARGV[4]) or 1

local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
local tokens     = tonumber(bucket[1]) or capacity
local lastRefill = tonumber(bucket[2]) or now

-- Refill tokens based on elapsed time
local elapsed  = math.max(0, now - lastRefill)
local newTokens = math.min(capacity, tokens + (elapsed / 1000) * rate)

if newTokens < consume then
  -- Not enough tokens — calculate wait time
  local waitMs = math.ceil((consume - newTokens) / rate * 1000)
  return { 0, math.floor(newTokens), waitMs }
end

-- Consume tokens
newTokens = newTokens - consume
redis.call('HMSET', key, 'tokens', newTokens, 'last_refill', now)
redis.call('PEXPIRE', key, math.ceil(capacity / rate * 1000))

return { 1, math.floor(newTokens), 0 }

Express Middleware with Proper Headers

// rate-limit.middleware.ts
import { Request, Response, NextFunction } from 'express';

export function createRateLimiter(limit: number) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const userId = req.user?.id ?? req.ip;
    const result = await slidingWindowRateLimit(userId, limit);

    // Set standard rate limit headers
    res.setHeader('X-RateLimit-Limit',     limit);
    res.setHeader('X-RateLimit-Remaining', result.remaining);
    res.setHeader('X-RateLimit-Reset',     result.resetAt);
    res.setHeader('RateLimit-Policy',      `${limit};w=60`);

    if (!result.allowed) {
      const retryAfter = result.resetAt - Math.floor(Date.now() / 1000);
      res.setHeader('Retry-After', retryAfter);

      return res.status(429).json({
        error: {
          code: 'RATE_LIMITED',
          message: 'Too many requests. Please slow down.',
          retry_after: retryAfter,
        },
      });
    }

    next();
  };
}

// Apply per-route
app.use('/api/v1/search',  createRateLimiter(10));   // 10/min — expensive
app.use('/api/v1/users',   createRateLimiter(100));  // 100/min — standard
app.use('/api/v1/webhooks',createRateLimiter(1000)); // 1000/min — high volume

Nginx Rate Limiting

# nginx.conf — http block
http {
  # Zone: 10MB stores ~160,000 IP addresses
  # Rate: 10 req/sec per IP (leaky bucket)
  limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

  # Per-user limiting using JWT sub claim (requires auth_request)
  limit_req_zone $http_x_user_id zone=user_limit:10m rate=100r/m;

  # Add headers to downstream
  limit_req_status 429;
  limit_conn_status 429;

  server {
    location /api/ {
      # Allow burst of 20, serve immediately (nodelay = token bucket behavior)
      limit_req zone=api_limit burst=20 nodelay;

      # Return proper JSON error
      error_page 429 @rate_limited;
      proxy_pass http://backend;
    }

    location @rate_limited {
      add_header Content-Type application/json;
      add_header Retry-After 1;
      return 429 '{"error":{"code":"RATE_LIMITED","message":"Too many requests"}}';
    }
  }
}