API Rate Limiting Implementation

Rate limiting protects APIs from abuse and ensures fair usage. Here's how to implement it effectively.

Rate Limiting Algorithms#

// 1. Fixed Window Counter
class FixedWindowCounter {
  private counts: Map<string, { count: number; windowStart: number }> = new Map();
  private windowMs: number;
  private maxRequests: number;

  constructor(windowMs: number, maxRequests: number) {
    this.windowMs = windowMs;
    this.maxRequests = maxRequests;
  }

  isAllowed(key: string): boolean {
    const now = Date.now();
    const windowStart = Math.floor(now / this.windowMs) * this.windowMs;

    const entry = this.counts.get(key);

    if (!entry || entry.windowStart !== windowStart) {
      this.counts.set(key, { count: 1, windowStart });
      return true;
    }

    if (entry.count >= this.maxRequests) {
      return false;
    }

    entry.count++;
    return true;
  }
}

// 2. Sliding Window Log
class SlidingWindowLog {
  private logs: Map<string, number[]> = new Map();
  private windowMs: number;
  private maxRequests: number;

  constructor(windowMs: number, maxRequests: number) {
    this.windowMs = windowMs;
    this.maxRequests = maxRequests;
  }

  isAllowed(key: string): boolean {
    const now = Date.now();
    const windowStart = now - this.windowMs;

    let timestamps = this.logs.get(key) || [];

    // Remove old timestamps
    timestamps = timestamps.filter((ts) => ts > windowStart);

    if (timestamps.length >= this.maxRequests) {
      this.logs.set(key, timestamps);
      return false;
    }

    timestamps.push(now);
    this.logs.set(key, timestamps);
    return true;
  }
}

// 3. Token Bucket
class TokenBucket {
  private buckets: Map<string, { tokens: number; lastRefill: number }> = new Map();
  private capacity: number;
  private refillRate: number; // tokens per second

  constructor(capacity: number, refillRate: number) {
    this.capacity = capacity;
    this.refillRate = refillRate;
  }

  isAllowed(key: string, tokensRequired: number = 1): boolean {
    const now = Date.now();
    let bucket = this.buckets.get(key);

    if (!bucket) {
      bucket = { tokens: this.capacity, lastRefill: now };
      this.buckets.set(key, bucket);
    }

    // Refill tokens
    const elapsed = (now - bucket.lastRefill) / 1000;
    bucket.tokens = Math.min(
      this.capacity,
      bucket.tokens + elapsed * this.refillRate
    );
    bucket.lastRefill = now;

    if (bucket.tokens >= tokensRequired) {
      bucket.tokens -= tokensRequired;
      return true;
    }

    return false;
  }
}

Express Middleware#

import { Request, Response, NextFunction } from 'express';
import Redis from 'ioredis';

const redis = new Redis();

interface RateLimitOptions {
  windowMs: number;
  maxRequests: number;
  keyGenerator?: (req: Request) => string;
  handler?: (req: Request, res: Response) => void;
  skip?: (req: Request) => boolean;
}

function rateLimiter(options: RateLimitOptions) {
  const {
    windowMs,
    maxRequests,
    keyGenerator = (req) => req.ip || 'unknown',
    handler = (req, res) => {
      res.status(429).json({
        error: 'Too Many Requests',
        retryAfter: Math.ceil(windowMs / 1000),
      });
    },
    skip = () => false,
  } = options;

  return async (req: Request, res: Response, next: NextFunction) => {
    if (skip(req)) {
      return next();
    }

    const key = `ratelimit:${keyGenerator(req)}`;

    try {
      // Use Redis for distributed rate limiting
      const current = await redis.incr(key);

      if (current === 1) {
        await redis.pexpire(key, windowMs);
      }

      const ttl = await redis.pttl(key);

      // Set rate limit headers
      res.set({
        'X-RateLimit-Limit': String(maxRequests),
        'X-RateLimit-Remaining': String(Math.max(0, maxRequests - current)),
        'X-RateLimit-Reset': String(Math.ceil((Date.now() + ttl) / 1000)),
      });

      if (current > maxRequests) {
        res.set('Retry-After', String(Math.ceil(ttl / 1000)));
        return handler(req, res);
      }

      next();
    } catch (error) {
      // Fail open - don't block requests if Redis is down
      console.error('Rate limiter error:', error);
      next();
    }
  };
}

// Usage
app.use(rateLimiter({
  windowMs: 60 * 1000, // 1 minute
  maxRequests: 100,
}));

// Different limits for different routes
app.use('/api/auth', rateLimiter({
  windowMs: 15 * 60 * 1000, // 15 minutes
  maxRequests: 5,
  keyGenerator: (req) => `auth:${req.ip}`,
}));

app.use('/api/upload', rateLimiter({
  windowMs: 60 * 60 * 1000, // 1 hour
  maxRequests: 10,
  keyGenerator: (req) => `upload:${req.user?.id || req.ip}`,
}));

Sliding Window Counter (Redis)#

// More accurate than fixed window, uses less memory than log
class SlidingWindowCounter {
  private redis: Redis;
  private windowMs: number;
  private maxRequests: number;

  constructor(redis: Redis, windowMs: number, maxRequests: number) {
    this.redis = redis;
    this.windowMs = windowMs;
    this.maxRequests = maxRequests;
  }

  async isAllowed(key: string): Promise<{ allowed: boolean; remaining: number; resetAt: number }> {
    const now = Date.now();
    const currentWindow = Math.floor(now / this.windowMs);
    const previousWindow = currentWindow - 1;

    const currentKey = `${key}:${currentWindow}`;
    const previousKey = `${key}:${previousWindow}`;

    // Get counts from both windows
    const [currentCount, previousCount] = await this.redis.mget(currentKey, previousKey);

    const current = parseInt(currentCount || '0', 10);
    const previous = parseInt(previousCount || '0', 10);

    // Calculate weighted count
    const windowProgress = (now % this.windowMs) / this.windowMs;
    const weightedCount = Math.floor(previous * (1 - windowProgress)) + current;

    if (weightedCount >= this.maxRequests) {
      return {
        allowed: false,
        remaining: 0,
        resetAt: (currentWindow + 1) * this.windowMs,
      };
    }

    // Increment current window
    await this.redis
      .multi()
      .incr(currentKey)
      .pexpire(currentKey, this.windowMs * 2)
      .exec();

    return {
      allowed: true,
      remaining: this.maxRequests - weightedCount - 1,
      resetAt: (currentWindow + 1) * this.windowMs,
    };
  }
}

Tiered Rate Limiting#

interface RateLimitTier {
  requests: number;
  windowMs: number;
}

interface UserTiers {
  free: RateLimitTier;
  basic: RateLimitTier;
  premium: RateLimitTier;
  enterprise: RateLimitTier;
}

const tiers: UserTiers = {
  free: { requests: 100, windowMs: 60 * 60 * 1000 },      // 100/hour
  basic: { requests: 1000, windowMs: 60 * 60 * 1000 },    // 1000/hour
  premium: { requests: 10000, windowMs: 60 * 60 * 1000 }, // 10000/hour
  enterprise: { requests: 100000, windowMs: 60 * 60 * 1000 }, // 100000/hour
};

function tieredRateLimiter() {
  return async (req: Request, res: Response, next: NextFunction) => {
    const user = req.user;
    const tier = user?.subscriptionTier || 'free';
    const limits = tiers[tier as keyof UserTiers];

    const key = `ratelimit:${user?.id || req.ip}`;
    const current = await redis.incr(key);

    if (current === 1) {
      await redis.pexpire(key, limits.windowMs);
    }

    res.set({
      'X-RateLimit-Limit': String(limits.requests),
      'X-RateLimit-Remaining': String(Math.max(0, limits.requests - current)),
      'X-RateLimit-Tier': tier,
    });

    if (current > limits.requests) {
      return res.status(429).json({
        error: 'Rate limit exceeded',
        tier,
        upgradeUrl: '/pricing',
      });
    }

    next();
  };
}

Cost-Based Rate Limiting#

// Different operations have different costs
const operationCosts: Record<string, number> = {
  'GET /api/users': 1,
  'POST /api/users': 5,
  'DELETE /api/users': 10,
  'POST /api/analyze': 100,
  'POST /api/export': 500,
};

function costBasedRateLimiter(options: {
  bucketCapacity: number;
  refillRate: number;
}) {
  const tokenBucket = new TokenBucket(
    options.bucketCapacity,
    options.refillRate
  );

  return async (req: Request, res: Response, next: NextFunction) => {
    const operation = `${req.method} ${req.path}`;
    const cost = operationCosts[operation] || 1;

    const key = req.user?.id || req.ip || 'unknown';
    const bucket = await tokenBucket.getState(key);

    res.set({
      'X-RateLimit-Limit': String(options.bucketCapacity),
      'X-RateLimit-Remaining': String(Math.floor(bucket.tokens)),
      'X-RateLimit-Cost': String(cost),
    });

    if (!tokenBucket.isAllowed(key, cost)) {
      return res.status(429).json({
        error: 'Insufficient tokens',
        cost,
        available: bucket.tokens,
        refillRate: options.refillRate,
      });
    }

    next();
  };
}

Client-Side Handling#

// API client with retry and backoff
class RateLimitedClient {
  private baseUrl: string;
  private maxRetries: number;

  constructor(baseUrl: string, maxRetries = 3) {
    this.baseUrl = baseUrl;
    this.maxRetries = maxRetries;
  }

  async request<T>(
    path: string,
    options: RequestInit = {}
  ): Promise<T> {
    let lastError: Error | null = null;

    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
      try {
        const response = await fetch(`${this.baseUrl}${path}`, options);

        // Log rate limit info
        const remaining = response.headers.get('X-RateLimit-Remaining');
        const limit = response.headers.get('X-RateLimit-Limit');

        if (remaining && parseInt(remaining) < 10) {
          console.warn(`Rate limit warning: ${remaining}/${limit} remaining`);
        }

        if (response.status === 429) {
          const retryAfter = response.headers.get('Retry-After');
          const waitMs = retryAfter
            ? parseInt(retryAfter) * 1000
            : Math.pow(2, attempt) * 1000;

          console.log(`Rate limited. Retrying in ${waitMs}ms...`);
          await this.sleep(waitMs);
          continue;
        }

        if (!response.ok) {
          throw new Error(`HTTP ${response.status}`);
        }

        return response.json();
      } catch (error) {
        lastError = error as Error;
      }
    }

    throw lastError || new Error('Request failed');
  }

  private sleep(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }
}

Best Practices#

Implementation:
✓ Use Redis for distributed systems
✓ Include rate limit headers
✓ Provide clear error messages
✓ Log rate limit events

Strategy:
✓ Different limits for different endpoints
✓ Higher limits for authenticated users
✓ Cost-based for expensive operations
✓ Fail open if limiter fails

UX:
✓ Return remaining quota in headers
✓ Include retry-after header
✓ Provide upgrade path
✓ Document limits clearly

Rate limiting protects APIs and ensures fair usage. Choose the right algorithm (token bucket for burst tolerance, sliding window for accuracy), use Redis for distributed deployments, and provide clear feedback to clients. Different endpoints and user tiers should have appropriate limits.