API Rate Limiting Complete Guide 2026: Algorithms, Implementation & 429 Handling

import { createClient } from 'redis';

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

// ── Sliding window rate limiter ────────────────────────────────────────────
async function slidingWindowLimit({ key, limit, windowSeconds }) {
  const now          = Date.now();
  const windowStart  = now - windowSeconds * 1000;
  const requestId    = now + '-' + Math.random().toString(36).slice(2);

  // Atomic pipeline — all operations execute together, no race conditions
  const [,, count] = await redis
    .multi()
    .zRemRangeByScore(key, 0, windowStart)          // remove requests older than window
    .zAdd(key, { score: now, value: requestId })    // record this request
    .zCard(key)                                      // count requests in window
    .expire(key, windowSeconds)                      // auto-expire the key
    .exec();

  const remaining = Math.max(0, limit - count);
  const resetAt   = new Date(now + windowSeconds * 1000).toISOString();

  return { allowed: count <= limit, count, remaining, limit, resetAt };
}

// ── Express middleware ─────────────────────────────────────────────────────
function createRateLimiter({ limit = 100, windowSeconds = 60, keyFn } = {}) {
  return async (req, res, next) => {
    // Default: rate limit by API key, fall back to IP
    const identifier = keyFn
      ? keyFn(req)
      : req.headers['x-api-key'] || req.ip;

    const key    = 'rl:' + identifier + ':' + Math.floor(Date.now() / (windowSeconds * 1000));
    const result = await slidingWindowLimit({ key, limit, windowSeconds });

    // Always set rate limit headers — even on success
    res.set({
      'X-RateLimit-Limit':     limit,
      'X-RateLimit-Remaining': result.remaining,
      'X-RateLimit-Reset':     result.resetAt,
      'X-RateLimit-Policy':    limit + ';w=' + windowSeconds,
    });

    if (!result.allowed) {
      const retryAfter = Math.ceil(windowSeconds - (Date.now() % (windowSeconds * 1000)) / 1000);
      res.set('Retry-After', retryAfter);

      return res.status(429).json({
        error: {
          code:    'RATE_LIMIT_EXCEEDED',
          message: 'Too many requests. Please slow down and retry after ' + retryAfter + ' seconds.',
          retryAfter,
          limit,
          resetAt: result.resetAt,
        },
      });
    }

    next();
  };
}

// ── Usage — apply globally and per-endpoint ────────────────────────────────
const globalLimit  = createRateLimiter({ limit: 1000, windowSeconds: 60 });
const searchLimit  = createRateLimiter({ limit: 10,   windowSeconds: 60 });   // expensive endpoint
const uploadLimit  = createRateLimiter({ limit: 5,    windowSeconds: 3600 }); // per hour

app.use(globalLimit);                         // 1000 req/min for all endpoints
app.get('/api/search', searchLimit, handler); // tighter: 10 searches/min
app.post('/api/upload', uploadLimit, handler);// very tight: 5 uploads/hour

// Token bucket — best for allowing controlled bursts
class TokenBucket {
  constructor({ capacity, refillRate }) {
    this.capacity   = capacity;   // max tokens (burst size)
    this.refillRate = refillRate; // tokens added per second
    this.tokens     = capacity;   // start full
    this.lastRefill = Date.now();
  }

  consume(count = 1) {
    this.#refill();

    if (this.tokens >= count) {
      this.tokens -= count;
      return { allowed: true, remaining: Math.floor(this.tokens) };
    }

    return {
      allowed:   false,
      remaining: 0,
      waitMs:    Math.ceil(((count - this.tokens) / this.refillRate) * 1000),
    };
  }

  #refill() {
    const now     = Date.now();
    const elapsed = (now - this.lastRefill) / 1000; // seconds
    this.tokens   = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
    this.lastRefill = now;
  }
}

// Example: 20 req burst allowed, refills at 5 req/sec (300 req/min steady state)
const bucket = new TokenBucket({ capacity: 20, refillRate: 5 });

// Middleware usage
function tokenBucketMiddleware(req, res, next) {
  const result = bucket.consume(1);
  if (!result.allowed) {
    res.set('Retry-After', Math.ceil(result.waitMs / 1000));
    return res.status(429).json({ error: { code: 'RATE_LIMIT_EXCEEDED', waitMs: result.waitMs } });
  }
  res.set('X-RateLimit-Remaining', result.remaining);
  next();
}

// ── On every successful response (not just 429) ───────────────────────────
HTTP/1.1 200 OK
X-RateLimit-Limit:     100          // max requests allowed in the window
X-RateLimit-Remaining: 73           // requests remaining before limit is hit
X-RateLimit-Reset:     2026-05-15T10:01:00Z  // ISO timestamp when window resets
X-RateLimit-Policy:    100;w=60     // IETF draft: 100 requests per 60 seconds

// ── On 429 Too Many Requests ───────────────────────────────────────────────
HTTP/1.1 429 Too Many Requests
Retry-After:           12           // seconds until client can retry (REQUIRED on 429)
X-RateLimit-Limit:     100
X-RateLimit-Remaining: 0
X-RateLimit-Reset:     2026-05-15T10:01:00Z

Content-Type: application/json

{
  "error": {
    "code":        "RATE_LIMIT_EXCEEDED",
    "message":     "Rate limit of 100 requests per 60 seconds exceeded. Retry after 12 seconds.",
    "retryAfter":  12,
    "limit":       100,
    "resetAt":     "2026-05-15T10:01:00Z",
    "docsUrl":     "https://docs.myapi.com/rate-limits"
  }
}

// ── Retry-After formats (HTTP spec accepts both) ────────────────────────────
Retry-After: 60                          // integer seconds (simpler, recommended)
Retry-After: Wed, 15 May 2026 10:01:00 GMT  // HTTP date format

// ── Exponential backoff with jitter — the correct 429 handler ─────────────
async function fetchWithRetry(url, options = {}, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);

    // Success — return immediately
    if (res.status !== 429) return res;

    // Final attempt — throw instead of waiting pointlessly
    if (attempt === maxRetries) {
      throw new Error('Rate limit exceeded after ' + maxRetries + ' retries');
    }

    // Read Retry-After header (always prefer server-specified wait time)
    const retryAfterHeader = res.headers.get('Retry-After');
    let delayMs;

    if (retryAfterHeader) {
      delayMs = parseInt(retryAfterHeader, 10) * 1000;
    } else {
      // Exponential backoff: 1s, 2s, 4s, 8s ... capped at 60s
      // Jitter: ±30% randomness prevents "thundering herd" — all clients retrying in sync
      const base  = Math.min(1000 * Math.pow(2, attempt), 60_000);
      const jitter = base * 0.3 * (Math.random() * 2 - 1);
      delayMs = Math.round(base + jitter);
    }

    console.warn('Rate limited. Waiting ' + delayMs + 'ms before retry ' + (attempt + 1) + ' of ' + maxRetries);
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
}

// ── Queue-based rate limit aware client ────────────────────────────────────
class RateLimitedClient {
  constructor({ requestsPerSecond = 10 }) {
    this.minInterval   = 1000 / requestsPerSecond;
    this.lastRequestAt = 0;
    this.queue         = [];
    this.processing    = false;
  }

  async fetch(url, options) {
    return new Promise((resolve, reject) => {
      this.queue.push({ url, options, resolve, reject });
      if (!this.processing) this.#processQueue();
    });
  }

  async #processQueue() {
    this.processing = true;
    while (this.queue.length > 0) {
      const wait = Math.max(0, this.minInterval - (Date.now() - this.lastRequestAt));
      if (wait > 0) await new Promise(r => setTimeout(r, wait));

      const { url, options, resolve, reject } = this.queue.shift();
      this.lastRequestAt = Date.now();
      fetchWithRetry(url, options).then(resolve).catch(reject);
    }
    this.processing = false;
  }
}

// Usage:
const client = new RateLimitedClient({ requestsPerSecond: 5 }); // 5 req/s max
const res    = await client.fetch('https://api.example.com/data');