Poorly designed rate limiting causes two symmetric kinds of damage: too permissive, and it protects nothing, letting a misconfigured or malicious client saturate the API in seconds; too strict or badly implemented, and it blocks legitimate users doing exactly what's expected of them, often at the worst possible moment (a spike of legitimate traffic during a promotion, for instance). The hard part isn't adding a limit, it's picking the right algorithm for the actual traffic pattern.

Fixed window: simple, with a known blind spot

The most direct implementation counts requests per client over a fixed time window (say, every calendar minute):

async function fixedWindowLimit(clientId, limit = 100) {
  const window = Math.floor(Date.now() / 60000); // current minute
  const key = `ratelimit:${clientId}:${window}`;

  const count = await redis.incr(key);
  if (count === 1) {
    await redis.expire(key, 60);
  }

  return count <= limit;
}

The structural flaw here: a client can send 100 requests right at the end of one window (second 59) and 100 more right at the start of the next one (second 0), that's 200 requests in two seconds, while staying within the 100-per-minute limit on each individual window. This isn't an implementation bug, it's inherent to fixed windows: they never look at traffic across the boundary between two windows.

Sliding window: fixing the blind spot

A sliding window removes that edge effect by counting requests over the last 60 seconds at any given instant, not over a fixed calendar window. The most direct Redis implementation uses a SORTED SET where every request is timestamped:

async function slidingWindowLimit(clientId, limit = 100, windowMs = 60000) {
  const now = Date.now();
  const key = `ratelimit:${clientId}`;

  await redis.zremrangebyscore(key, 0, now - windowMs);
  const count = await redis.zcard(key);

  if (count >= limit) {
    return false;
  }

  await redis.zadd(key, now, `${now}-${Math.random()}`);
  await redis.expire(key, Math.ceil(windowMs / 1000));
  return true;
}

zremrangebyscore purges entries older than the window before counting, which guarantees the count always reflects exactly the last 60 sliding seconds, regardless of where in time the check lands. The cost: every limit check now needs several Redis operations instead of one, and the SORTED SET grows with request volume per client before it gets trimmed.

Token bucket: absorbing legitimate bursts

The token bucket starts from a different principle: each client has a reservoir of tokens that refills at a constant rate (say, 10 tokens per second) up to a maximum capacity. Every request consumes a token; with none available, the request gets rejected.

-- token_bucket.lua (run via EVAL to guarantee atomicity)
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local refillRate = tonumber(ARGV[2])
local now = tonumber(ARGV[3])

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

local elapsed = math.max(0, now - lastRefill)
tokens = math.min(capacity, tokens + elapsed * refillRate / 1000)

if tokens < 1 then
  redis.call('HMSET', key, 'tokens', tokens, 'timestamp', now)
  return 0
end

tokens = tokens - 1
redis.call('HMSET', key, 'tokens', tokens, 'timestamp', now)
redis.call('EXPIRE', key, 3600)
return 1

The token bucket's advantage over the sliding window: it naturally absorbs a one-off burst as long as the reservoir still holds tokens accumulated during a quiet period, which matches the real pattern of a legitimate client much better (a mobile app that syncs several screens at once on launch, for instance), without ever allowing an average throughput above the intended limit. This is the algorithm behind most commercial API gateways (Stripe, GitHub) because it best reconciles protection with tolerance for legitimate spikes.

Diagnosing: who is actually being blocked

Before tightening or loosening a limit, you need to know who it's hitting. Logging every 429 rejection with the client id, the endpoint, and the observed rate lets you tell apart two very different populations: clients that occasionally exceed the limit (often a client-side bug, a badly configured retry loop) and clients that exceed it consistently (often abuse or scraping).

app.use((req, res, next) => {
  res.on('finish', () => {
    if (res.statusCode === 429) {
      logger.warn('rate_limit_exceeded', {
        clientId: req.user?.id ?? req.ip,
        endpoint: req.path,
        timestamp: Date.now(),
      });
    }
  });
  next();
});

A spike of 429s concentrated on a single client and a single endpoint, right after a frontend deploy, almost always points to a client-side regression (a useEffect stuck in a loop, a retry with no backoff) rather than real abuse. Tightening the limit in that case would just mask the actual bug.

Granularity: by IP, by user, or by API key

Limiting by IP address protects against unauthenticated abuse, but unfairly penalizes every legitimate user behind a shared IP (a corporate network, a mobile carrier's NAT) by making them share the same quota. Limiting by authenticated user id or API key is more precise but does nothing for public unauthenticated endpoints (login, signup), which remain the prime target for credential-stuffing attacks.

Common practice combines both levels: a broad per-IP limit on unauthenticated endpoints to contain raw abuse, and a per-account or per-API-key limit on authenticated endpoints, with quotas differentiated by pricing tier.

const limits = {
  free: { requests: 100, windowMs: 60000 },
  pro: { requests: 1000, windowMs: 60000 },
  enterprise: { requests: 10000, windowMs: 60000 },
};

async function checkLimit(req) {
  const plan = req.user?.plan ?? 'anonymous';
  const config = limits[plan] ?? { requests: 20, windowMs: 60000 };
  return slidingWindowLimit(req.user?.id ?? req.ip, config.requests, config.windowMs);
}

Responding to the client correctly

A rate limit rejection should always include the standard headers that let the client adapt instead of blindly retrying in a loop:

res.set({
  'X-RateLimit-Limit': limit,
  'X-RateLimit-Remaining': Math.max(0, limit - count),
  'X-RateLimit-Reset': resetTimestamp,
  'Retry-After': retryAfterSeconds,
});
res.status(429).json({ error: 'rate_limit_exceeded' });

Retry-After is the difference between a client that retries intelligently after the indicated delay and one that retries immediately in a tight loop, which only makes worse the load the rate limiting was supposed to contain.

When the easy fix isn't enough

Rate limiting implemented purely in application code protects the API process itself, but not the upstream infrastructure (database, a third-party service billed per call) if several API instances share those resources without a coordinated global limit. In that case, rate limiting has to happen at a shared gateway layer (Kong, a reverse proxy with a limiting module, or a managed service like AWS API Gateway), with a counter centralized in a shared Redis instance across every API process, rather than a counter local to each process that underestimates real aggregate traffic.

For distributed attacks spread across a large number of IPs (a botnet), per-client rate limiting alone stops being enough: it needs to be combined with behavioral detection (fingerprinting, adaptive CAPTCHA) upstream of the API.

Takeaway

A fixed window is simple but lets throughput double at the boundary between windows; a sliding window fixes that at the cost of more Redis operations; a token bucket is the best compromise for absorbing legitimate bursts without loosening the average limit. Either way, logging rejections with enough context to tell a client bug from real abuse keeps you from fixing the wrong thing.