Key Points
- Rate limiting protects your API from abuse, runaway costs, and SLO breaches — it is not optional in production.
- Token bucket handles bursts gracefully; sliding window counter gives the most accurate enforcement; fixed window is the easiest to implement but has an exploitable boundary flaw.
- Single-instance in-memory rate limiting is silently wrong behind a load balancer — use Redis with an atomic Lua script.
- Every 429 response must include
Retry-After; every rate-limited endpoint must exposeX-RateLimit-*headers. - Different endpoints deserve different limits — never apply a single global cap to your entire surface area.
Introduction
An API without rate limiting is an invitation. Scrapers, buggy clients, and deliberate attackers will push your service to its resource ceiling and take it down for everyone else. I've retrofitted rate limiting onto APIs that launched without it, and every time the conversation starts the same way: an incident, a surprise cloud bill, or a customer screaming that a single bad actor took the service down for everyone. Rate limiting is how you enforce fair use, protect downstream dependencies, and keep your SLOs intact when traffic spikes. This article walks through the four major rate limiting algorithms, explains when to choose each one, and shows you a complete Express implementation — from in-memory token bucket to distributed sliding window on Redis — with every 429 response correctly formatted per RFC 7807.
Why Rate Limiting Matters
Rate limiting solves four distinct problems, and conflating them leads to misconfigured limits.
Abuse prevention. Without limits, a single bad actor can saturate your CPU, fill your database connection pool, or run up your cloud bill. Limits put a ceiling on the damage any one client can cause.
Cost control. If your API calls paid third-party services — LLM inference, geocoding, payment processing — uncapped traffic translates directly to uncapped spend. A per-key limit is a billing guardrail.
Fair use. Free tiers exist because you want to let developers experiment. Without limits, the noisiest client starves everyone else. Rate limiting enforces the implicit social contract of a shared platform.
SLO protection. Your p99 latency guarantee assumes some distribution of traffic. A burst that doubles your request volume breaks that assumption. Rate limiting lets you absorb spikes without blowing your error budget.
Algorithm Comparison
The four algorithms you will encounter in production each make different tradeoffs between accuracy, memory, implementation complexity, and burst tolerance. I default to sliding window log on Redis for anything distributed and token bucket for single-instance deployments where burst tolerance matters — fixed window is a trap I've stopped recommending to teams once they understand the boundary math.
| Algorithm | Accuracy | Burst Handling | Memory | Complexity |
|---|---|---|---|---|
| Token Bucket | High | Allows controlled bursts | Low (one record/client) | Medium |
| Sliding Window | Very High | Smooth, no burst spike | Medium (timestamps per client) | Medium-High |
| Fixed Window | Low (boundary flaw) | Allows 2× limit at boundary | Low (one counter/client) | Low |
| Leaky Bucket | High | No bursts; strict output rate | Low | Medium |
Fixed Window is the easiest to implement: increment a counter, reset it every minute. The flaw is that a client can fire their full quota at 11:59 and again at 12:00, doubling the effective rate at the boundary — every single window. I've seen a scraper exploit exactly this pattern against a search endpoint: it was scripted to fire its burst precisely at the clock tick, and the fixed window counter reset saved it every time — 200 requests per minute against a system sized for 100, consistently, until a downstream Elasticsearch cluster fell over.
Fixed window boundary burst — 100 req/min limit, client fires 200 requests in 2 seconds:
Token Bucket maintains a bucket per client. Tokens refill at a steady rate up to a maximum. Each request consumes one token; when the bucket is empty, the request is rejected. Clients can legitimately burst up to the bucket capacity, which is useful for batch workflows that fire in short windows.
Sliding Window Counter is a hybrid: it blends the current window counter with the previous window's count, weighted by how far through the current window you are. It eliminates the boundary burst without storing per-request timestamps.
Sliding Window Log stores a timestamp for every request in a sorted set. It is the most accurate and the most memory-intensive. The Redis Lua script shown later uses this approach because Redis sorted sets make the atomic timestamp management cheap.
Leaky Bucket processes requests at a constant output rate regardless of input burst. Useful when you are protecting a downstream service with a strict throughput ceiling, not when you want to allow short bursts.
Decision tree — picking your algorithm:
Token Bucket: State Machine
Before writing code, it helps to reason about the token bucket as a state machine. There are exactly three transitions:
The bucket never goes below zero. A refill does not carry over unused capacity from previous intervals — tokens accumulate only up to capacity.
Request Flow Through Rate Limit Middleware
Every inbound request hits the middleware before your route handler. The middleware's job is to make a binary decision — allow or reject — and set the right headers either way.
The critical path: the Lua script executes atomically on Redis, so concurrent requests across multiple server instances cannot race each other and double-spend the same quota slot.
Rate Limiting Strategies
Choosing an algorithm is only half the decision. You also need to decide what the rate limit key is — what unit of identity you are counting against.
Per-IP is the default and requires no authentication. It works for public endpoints but breaks behind NAT (shared corporate IPs) and is easy to bypass with proxy rotation.
Per-API-key is what I use for every authenticated API — the key identifies the calling application, not the network path, which means you get accurate accounting even when clients come through a proxy or a corporate VPN. Combine it with per-IP limits to prevent key-sharing across many IPs.
Per-endpoint recognizes that a GET /search that fans out to 10 database queries deserves a tighter limit than a GET /healthz. Apply tighter limits to expensive operations and looser limits to cheap ones.
Global limits cap total throughput regardless of who is calling. Useful as a last-resort circuit breaker — if everything else fails, you still have a ceiling.
In practice, layer these strategies. A well-configured API might have: a global limit of 10,000 req/min, a per-key limit of 1,000 req/hr, and a tighter per-endpoint limit of 50 req/min on write operations.
Response Headers and 429 Format
Rate Limit Headers
Return these headers on every response from a rate-limited endpoint, not just on rejections. Clients need the Remaining value to pace themselves.
| Header | Value | Example |
|---|---|---|
X-RateLimit-Limit |
Total requests allowed per window | 1000 |
X-RateLimit-Remaining |
Requests left in current window | 847 |
X-RateLimit-Reset |
Window reset time, Unix epoch seconds | 1738972800 |
Retry-After |
Seconds to wait before retrying (only on 429) | 47 |
RFC 7807 Problem Details
A 429 with a plain-text body is useless to a machine client. Use RFC 7807 application/problem+json:
{
"type": "https://example.com/problems/rate-limit-exceeded",
"title": "Too Many Requests",
"status": 429,
"detail": "You have exceeded 1000 requests per hour. Reset at 2027-02-01T12:00:00Z.",
"instance": "/api/v1/data"
}
Always set Content-Type: application/problem+json. Always include Retry-After. Clients that parse RFC 7807 can back off automatically without custom logic.
Express Implementation with express-rate-limit
express-rate-limit handles the boilerplate — window tracking, counter management, header injection. The key customization point is the keyGenerator function, which controls what identity you rate-limit against.
import rateLimit from "express-rate-limit";
import type { Request, Response } from "express";
import { problem } from "./problem";
/**
* Creates a per-IP rate limiter for public endpoints.
*
* @remarks
* Uses the forwarded IP from X-Forwarded-For in production (set trust proxy).
* @see {@link https://www.npmjs.com/package/express-rate-limit}
*/
export const publicLimiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
limit: 100,
standardHeaders: "draft-8",
legacyHeaders: false,
keyGenerator: (req: Request) =>
(req.headers["x-forwarded-for"] as string)?.split(",")[0].trim() ??
req.socket.remoteAddress ??
"unknown",
handler: (req: Request, res: Response) => {
const resetEpoch = Math.ceil(Date.now() / 1000) + 15 * 60;
res.setHeader("Retry-After", "900");
res.status(429).json(
problem({
type: "https://example.com/problems/rate-limit-exceeded",
title: "Too Many Requests",
status: 429,
detail: `Public endpoint limit: 100 requests per 15 minutes. Resets at ${new Date(resetEpoch * 1000).toISOString()}.`,
instance: req.path,
})
);
},
});
/**
* Creates a per-API-key rate limiter for authenticated endpoints.
*
* @remarks
* Falls back to IP if no API key is present, which will trigger
* the auth middleware before this limiter runs in practice.
* @param limit - Requests allowed per hour
* @see {@link https://tools.ietf.org/html/rfc6585#section-4}
*/
export const apiKeyLimiter = rateLimit({
windowMs: 60 * 60 * 1000, // 1 hour
limit: 1000,
standardHeaders: "draft-8",
legacyHeaders: false,
keyGenerator: (req: Request) =>
(req.headers["x-api-key"] as string) ??
req.socket.remoteAddress ??
"unknown",
handler: (req: Request, res: Response) => {
res.setHeader("Retry-After", "3600");
res.status(429).json(
problem({
type: "https://example.com/problems/rate-limit-exceeded",
title: "Too Many Requests",
status: 429,
detail: "API key limit: 1000 requests per hour.",
instance: req.path,
})
);
},
});
The keyGenerator on apiKeyLimiter extracts the X-API-Key header value. Every unique key gets its own counter, isolated from other keys. One misbehaving client cannot exhaust quota for another.
Distributed Rate Limiting
Single-instance in-memory rate limiting is wrong behind a load balancer. If you run three Express instances each configured for 100 req/min, a single client can reach all three and make 300 requests in one minute — three times your intended limit. The dangerous part is that it fails silently: your logs show each instance enforcing its limit perfectly, and you have no idea the total throughput is a multiple of what you intended until something downstream collapses.
Instance A: client sees 0–100 ✓ (limit not exceeded)
Instance B: client sees 0–100 ✓ (limit not exceeded)
Instance C: client sees 0–100 ✓ (limit not exceeded)
Total actual requests: 300/min — 3× your limit
The fix is a shared counter that all instances read and write atomically. Redis is the standard choice. The atomic part matters: a non-atomic read-then-write sequence has a race condition. Two instances can read the same count, both decide the limit is not exceeded, and both allow requests, causing a double-spend.
The solution is a Lua script executed with EVAL. Redis executes Lua scripts atomically — no other command runs between steps.
-- Sliding window log via Redis sorted set
-- KEYS[1] = rate limit key (e.g. "rl:user:abc123:/api/v1/data")
-- ARGV[1] = current timestamp (milliseconds)
-- ARGV[2] = window size (milliseconds)
-- ARGV[3] = limit (max requests)
-- ARGV[4] = request TTL (slightly longer than window, for cleanup)
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
local ttl = tonumber(ARGV[4])
local cutoff = now - window
-- Remove timestamps older than the window
redis.call('ZREMRANGEBYSCORE', key, '-inf', cutoff)
-- Count requests in the current window
local count = redis.call('ZCARD', key)
if count >= limit then
return {0, count} -- rejected
end
-- Add current request timestamp (score = timestamp, member = unique id)
redis.call('ZADD', key, now, tostring(now) .. ':' .. math.random(1e9))
redis.call('PEXPIRE', key, ttl)
return {1, count + 1} -- allowed, new count
This script runs the prune → count → add sequence without any possibility of interleaving from another client. The sorted set's score is the request timestamp, so ZREMRANGEBYSCORE efficiently prunes expired entries on every call.
The TypeScript wrapper:
import Redis from "ioredis";
const lua = `
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
local ttl = tonumber(ARGV[4])
local cutoff = now - window
redis.call('ZREMRANGEBYSCORE', key, '-inf', cutoff)
local count = redis.call('ZCARD', key)
if count >= limit then return {0, count} end
redis.call('ZADD', key, now, tostring(now) .. ':' .. math.random(1e9))
redis.call('PEXPIRE', key, ttl)
return {1, count + 1}
`;
/**
* Result of a distributed rate limit check.
*
* @remarks
* `allowed` is false when the request should be rejected with 429.
* `count` is the number of requests in the current window after this check.
*/
export interface RateLimitResult {
allowed: boolean;
count: number;
}
/**
* Checks the sliding window rate limit for a given key using Redis.
*
* @param redis - Connected ioredis client
* @param key - Unique rate limit key (e.g. "rl:apikey:abc123")
* @param windowMs - Window size in milliseconds
* @param limit - Maximum requests allowed in the window
* @returns Whether the request is allowed and the current request count
* @see {@link https://redis.io/docs/manual/programmability/eval-intro/}
*/
export async function checkRateLimit(
redis: Redis,
key: string,
windowMs: number,
limit: number
): Promise<RateLimitResult> {
const now = Date.now();
const ttl = windowMs + 1000; // slight buffer for cleanup
const result = (await redis.eval(lua, 1, key, now, windowMs, limit, ttl)) as [
number,
number
];
return { allowed: result[0] === 1, count: result[1] };
}
Common Mistakes
1. Single-instance rate limiting in a distributed system.
In-memory rate limiting with express-rate-limit (default memory store) is invisible to other processes. Deploy three instances and your limit triples. I've seen teams add rate limiting as an afterthought, test it locally against a single process, ship to a four-node cluster, and spend three days on an incident because a well-meaning developer's retry loop was effectively throttle-free across the load balancer. Use a shared store — rate-limit-redis for express-rate-limit, or your own Redis Lua middleware for the sliding window log approach.
2. Not returning Retry-After.
RFC 6585 §4 requires Retry-After on 429 responses. Without it, clients have no signal on when to retry. They either hammer your API immediately (making things worse) or use an arbitrary exponential backoff. I've watched a mobile app back off for 30 seconds on a 1-minute window limit — the user retried manually and got 429 again, then gave up and filed a bug report. The window had reset by then; the correct Retry-After: 47 would have fixed it automatically. Tell them exactly how long to wait. The value is in seconds, matching your window reset time.
3. Fixed window burst attacks at the window boundary.
A 100 req/min fixed window limit allows a client to fire 100 requests at 11:59:59 and 100 more at 12:00:01 — 200 requests in 2 seconds against your system. Every minute, indefinitely. Sliding window eliminates this by measuring the actual rolling window, not a clock-aligned bucket.
4. Rate limiting after expensive computation.
If your middleware calls a database to validate an API key before checking the rate limit, you pay the database cost even for requests you are about to reject. Put rate limiting as early in the middleware chain as possible. Validate the key format (cheap, stateless) before the database lookup, and put the rate limit check before the database validation wherever possible.
5. Applying the same limit to every endpoint.
A POST /upload that writes a 10 MB file to S3 deserves a tighter limit than a GET /status that reads from an in-memory cache. A one-size-fits-all rate limit either over-restricts cheap endpoints or under-restricts expensive ones. Model your limits around the cost of each operation, not a single global ceiling.
Full Example
The complete working implementation lives at GitHub link → cloud-apis/rate-limiting-strategies/.
It includes:
- A custom in-memory token bucket implementation (no external dependency)
-
express-rate-limitconfigured for per-IP and per-API-key strategies - A Redis-backed sliding window with the Lua script above
- RFC 7807
application/problem+jsonon every 429 -
X-RateLimit-*headers on every response
Setup:
npm install
npm run dev
Try the rate limit:
# Hit the per-IP limit on the public endpoint
for i in {1..5}; do
curl -s -o /dev/null -w "%{http_code} remaining=%{header.x-ratelimit-remaining}\n" \
http://localhost:3000/public
done
# Hit the per-API-key limit
curl -i http://localhost:3000/api/v1/data -H "X-API-Key: demo-key"
What a 429 response looks like:
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 3600
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1738972800
{
"type": "https://example.com/problems/rate-limit-exceeded",
"title": "Too Many Requests",
"status": 429,
"detail": "API key limit: 1000 requests per hour.",
"instance": "/api/v1/data"
}
Conclusion
Rate limiting is infrastructure, not a feature. If you take one thing from this article: in-memory rate limiting behind a load balancer is not rate limiting — it is a false sense of security that will fail exactly when you need it most, under real attack load. Ship with Redis-backed sliding window from day one, return Retry-After on every 429, and model your limits per endpoint rather than globally. The teams I've seen get this right don't treat it as an afterthought; they wire the middleware before the first route handler is ever written.
Further Reading
- RFC 6585 — Additional HTTP Status Codes (§4: 429 Too Many Requests)
- RFC 7807 — Problem Details for HTTP APIs
- express-rate-limit — npm package documentation
- Redis Rate Limiting — Official Redis tutorial with 5 algorithms
- MDN: Retry-After header reference
If this helped, a like and a follow are appreciated — and if you've solved this differently, drop a comment, I'd like to hear it.
Bry Writes Code — cloud and AI infrastructure specialist. Building rate-limited APIs? Let's talk.




Top comments (0)