Rate limiting: how to design limits that slow abuse and still let real customers back in
A rate limit counts what a client does against a key over a window, and decides what happens when the count runs out.
This guide covers what to count and against which key (an account, an address, a device or the whole route), how window choices feel to a real user, what a good 429 response says, why counters kept in each server multiply the limit, what to do when the counter store is down, and how a limited customer gets back in. It comes with a design worksheet, a verification table for low-volume checks on staging, and a local Node.js lab with a regression test.
In this guide
Rate-limit design worksheet, verification table and lab
An illustration written for this page, not client code. Part A is a design worksheet for seven kinds of endpoint, from sign-in to a public API: the keys to count against, your limit and window, the response at the limit and the way back in for a real customer, each with its basis.
How to use itHide the instructions
Part B is a verification table of low-volume staging checks: bursts, one check per key, Retry-After, counters across instances, an unreachable counter store and the way back in. Parts C to G hold a Node.js lab with nothing to install, its output recorded on Node.js 26.0.0, and a regression test that fails on the careless version.
rate-limiting.txt
RATE-LIMIT DESIGN WORKSHEET, VERIFICATION TABLE AND LAB
Written for this page. Part A is a worksheet you fill in for your own application. Part B is a set of checks to run against your own staging environment. Parts C to G are a lab: an illustration that runs on one machine, with invented accounts and invented addresses. It shows how a limit is counted and answered. It measures nothing about capacity, speed or load.
==== PART A. RATE-LIMIT DESIGN WORKSHEET ====
One block per kind of endpoint a business site tends to have. For each dimension, write your limit and your window from your own traffic: look at what real customers do on a busy day, set the limit above that, and write down why. This page gives no universal numbers. Where a source gives a figure, it is quoted with its conditions. Every block also names what a real customer does to get back in, because a limit with no way back sends people to your support line.
ASVS 5.0 requirement 6.1.1 (Level 1) asks that application documentation defines how controls such as rate limiting, anti-automation and adaptive response are used to defend against attacks such as credential stuffing and password brute force, and makes clear how these controls are configured and prevent malicious account lockout. A filled-in A1 is a start on that document.
A1. SIGN-IN
Protects: accounts from password guessing.
Account (the username as typed): your limit per your window, counting attempts since the account's last successful sign-in.
Device (a browser that has signed in to this account before): your limit per your window, as an allowance of its own.
Address (all usernames from one address): your limit per your window.
Global ceiling (browsers not seen before, across the whole route): your limit per your window.
Why these numbers: your reason, from your traffic.
At the limit: 429 with Retry-After, and a message that says when to try again and what else works. The same reply whether or not the username is an account.
Way back in: wait for the time in Retry-After; sign in from a browser that has signed in before; or reset the password.
Basis: The OWASP Authentication Cheat Sheet says the counter of failed logins should be associated with the account itself, rather than the source IP address, to prevent an attacker making login attempts from a large number of different IP addresses. NIST SP 800-63B-4 Sec. 3.2.2, written for government information systems, says that unless an authenticator's own description says otherwise, the verifier SHALL limit consecutive failed attempts with one authenticator on one account to no more than 100 by disabling that authenticator, that 100 is an upper bound, and that agencies MAY impose lower limits. The same section says that after a successful authentication the verifier SHOULD disregard earlier failed attempts for the authenticators used. The device allowance follows OWASP's "Slow Down Online Guessing Attacks with Device Cookies". The Authentication Cheat Sheet says that when designing an account lockout system, care must be taken to prevent it from being used to cause a denial of service by locking out other users' accounts, and that one way this could be performed is to allow the use of the forgotten password functionality to log in, even if the account is locked out. The address limit, the global ceiling and counting unknown usernames the same way are this page's advice.
A2. PASSWORD RESET REQUEST
Protects: the customer's inbox or phone, and the cost of every email or text message you send.
Identifier (the email address or phone number as typed): your limit per your window.
Address: your limit per your window.
Global ceiling: your limit per your window, sized to what your email or SMS bill can absorb.
Why these numbers: your reason, from your traffic.
At the limit: 429 with Retry-After, counted the same way whether or not the identifier has an account. The account itself is not locked.
Way back in: the link already sent still works; another can be requested after the Retry-After time.
Basis: The OWASP Forgot Password Cheat Sheet says to implement protections against excessive automated submissions, such as rate limiting on a per-account basis, requiring a CAPTCHA or other controls, because otherwise an attacker could flood the user's intake system, such as an email inbox or SMS, with useless requests, and says accounts should not be locked out in response to a forgotten password attack. API2:2023 says credential recovery and forgot-password endpoints should be treated as login endpoints for brute force, rate limiting and lockout protections. API4:2023 notes that some resources are paid for per request, such as emails, SMS and phone calls, and suggests limiting how often a single client or user can execute a single operation, giving requesting password recovery without visiting the one-time URL as one of its two examples. The address limit and the global ceiling are this page's advice.
A3. ONE-TIME CODE CHECK
Protects: the code from being guessed.
The pending sign-in and its account: your limit per your window, counting wrong codes. Sending a new code does not start the count again.
Address and global ceiling: your limit per your window.
Why these numbers: your reason, from your traffic.
At the limit: 429 with Retry-After, and a message that says how long to wait.
Way back in: wait, then enter a fresh code. A lost phone or key is account recovery, covered in the MFA security guide.
Basis: NIST SP 800-63B-4 Sec. 3.1.3.2 says that if an out-of-band authentication secret is less than 64 bits long, the verifier SHALL implement a rate-limiting mechanism that effectively limits the total number of consecutive failed attempts on the account as described in Sec. 3.2.2, and that generating a new authentication secret SHALL NOT reset the failed authentication count. Sec. 3.1.4.2 says single-factor OTP verifiers SHOULD implement rate limiting, and SHALL if the authenticator output is less than 64 bits. ASVS 5.0 requirement 6.6.3 (Level 2) asks that a code-based out-of-band mechanism is protected against brute force attacks by using rate limiting, and says to consider a code with at least 64 bits of entropy. NIST's usability considerations say to allow at least 10 entry attempts for authenticators that require the user to enter the authenticator output, and, for rate limiting, to inform users how long they have to wait until the next attempt. API4:2023 gives validating an OTP as the other of its two examples of an operation to limit per client or user. The address limit and the global ceiling are this page's advice.
A4. SIGN-UP
Protects: your user table and your email budget from mass registration.
Identifier (the email address being registered): one verification email per address in your window.
Address, and device or session: your limit per your window.
Global ceiling: your limit per your window.
Why these numbers: your reason, from your traffic.
At the limit: 429 with Retry-After. For an address many people share, such as an office, consider a challenge before a refusal.
Way back in: wait, or complete the challenge.
Basis: ASVS 5.0 requirement 2.4.1 (Level 2) asks for anti-automation controls against excessive calls to application functions that could lead to data exfiltration, garbage-data creation, quota exhaustion, rate-limit breaches, denial-of-service, or overuse of costly resources. Cloudflare's rate limiting documentation describes requests under NAT sharing the same IP address. The dimensions and the challenge are this page's advice.
A5. SEARCH
Protects: your database, and everyone else's response times, from one heavy user; and your listings from being copied out page by page.
Signed-in account or session: your limit per your window.
Address, for visitors who are not signed in: your limit per your window.
Global ceiling: your limit per your window.
Also: a maximum page size set on the server, whatever the request asks for.
Why these numbers: your reason, from your traffic.
At the limit: 429 with Retry-After.
If the counter store is down: fail open to a smaller limit counted in each instance.
Way back in: wait; or sign in, for the account's own allowance.
Basis: ASVS 5.0 requirement 2.4.1 (Level 2), as in A4. API4:2023 recommends server-side validation of the parameter that controls the number of records returned. The dimensions and the fail-open choice are this page's advice.
A6. COSTLY REPORT OR EXPORT
Protects: server time, memory and any bill charged per use.
Account, and the customer business it belongs to if you sell to businesses: your limit per your window, counted in units of work rather than requests; plus how many may run at once.
Global ceiling: how many such jobs may run at once across the site.
Why these numbers: your reason, from your traffic.
At the limit: 429 with Retry-After, or accept the job into a queue and say when it will be ready.
Way back in: the queued job finishes and its result stays available to download.
Basis: API4:2023 says an API is vulnerable if at least one of a list of limits is missing or set inappropriately, including execution timeouts, maximum allocable memory, and the number of operations performed in a single API client request (its example is GraphQL batching). Its second attack scenario shows a traditional rate limit on a GraphQL endpoint bypassed by sending many upload operations in one request. ASVS 5.0 requirement 2.4.1 names overuse of costly resources. Cloudflare documents complexity-based rate limiting, which it offers only to some customers, in which the origin server returns a score for the cost of each request. Units of work, concurrency and the queue are this page's advice.
A7. PUBLIC API
Protects: every other client from one heavy client.
API key or client: your limit per your window, with a stricter one for endpoints that cost more or that authenticate.
Address, for requests without a key: your limit per your window.
Global ceiling: your limit per your window.
Why these numbers: your reason, from your traffic.
At the limit: 429 with Retry-After. The RateLimit-Policy and RateLimit fields come from an IETF Internet-Draft, not an RFC (Part B, row R2).
Way back in: the client waits as Retry-After says, and your API documentation states the limits.
Basis: API4:2023 recommends a limit on how often a client can interact with the API within a defined timeframe, says rate limiting should be fine tuned based on the business needs, and says some endpoints might require stricter policies. API2:2023 says anti-brute force mechanisms on authentication endpoints should be stricter than the regular rate limiting on the API. The response comes from RFC 6585 and RFC 9110.
==== PART B. VERIFICATION TABLE ====
Run these against your own staging environment, with test accounts made for the purpose and limits lowered so that a few requests reach them. Each row sends a few dozen requests at most. None is a load test: load, volumetric and denial-of-service testing is separate work for a load-testing specialist, with your host's written approval. Do not run these against a system you do not own or are not authorised in writing to test. Keep real customers' accounts out of every row. The lab id after each row is the matching run in Part D.
BURST TESTS
B1. Short burst just over the limit (lab B1)
Question: does the limit exist, and does it stop at the number you set?
Steps: from one test address, send your limit plus two requests within a second.
Expected: exactly your limit succeed; the rest get 429 with Retry-After.
A failure means: more than your limit succeeded. The limit is missing, counted per instance (row D1), or keyed on something the burst changed.
B2. The same burst spread across the window (lab B2)
Question: does the limit count over the whole window, or only over a second or two?
Steps: send the same number of requests spread evenly across one window.
Expected: the same result as B1.
A failure means: the limit checks a short-term rate only, so a slow, steady sender never reaches it.
B3. Window edge (lab B3)
Question: can two windows' worth pass in a few seconds?
Steps: send your limit one second before a window boundary and your limit again one second after it.
Expected with a sliding window: the second batch is refused. With a fixed window it passes, which may be acceptable for search and is double the guesses on sign-in.
A failure means: the endpoint allows twice what the worksheet says at every boundary.
ONE TEST PER DIMENSION
P1. One account, two addresses (lab P1)
Question: is the account limit counted across addresses?
Steps: send wrong passwords for one test account, alternating between two addresses, until a few past the account limit.
Expected: refusals start at the account limit, whichever address sends the next attempt.
A failure means: the account is counted per address, so each new address gets a fresh allowance on the same account.
P2. Many accounts, one address (lab P2)
Question: does one address trying many accounts reach a limit?
Steps: one wrong password for each of a dozen test accounts, from one address.
Expected: refusals start at the address limit.
A failure means: one address can try one password on every account, and no per-account limit will ever see it.
P3. Global ceiling (lab P3)
Question: does the whole route have a ceiling, and can a known customer still get in when it is reached?
Steps: from several addresses, send wrong passwords for invented usernames that are not accounts, until a few past the ceiling. Then sign in to a test account from a browser that has signed in before, and from one that has not.
Expected: refusals start at the ceiling. The known browser signs in. The new browser is refused, or challenged, with a Retry-After.
A failure means: no ceiling, or a ceiling that refuses everyone including returning customers.
P4. Which address is counted (lab P4)
Question: does the limit count the address your own proxy saw, or one the client wrote?
Steps: send a burst in which each request carries its own X-Forwarded-For header naming a different address.
Expected: the count follows the address your proxy recorded, and the burst stops at the address limit.
A failure means: anyone can reset the address limit by changing a header.
RETRY-AFTER
R1. Present, valid and honoured (lab R1)
Question: does every refusal say when to come back, in a form a client can read, and is it true?
Steps: send until the first 429. Read Retry-After. Wait that many seconds and send once more.
Expected: Retry-After is present on every 429 and every 503 your limits send, as a whole number of seconds or an HTTP-date in the IMF-fixdate form (for example Fri, 31 Dec 1999 23:59:59 GMT). The request after the wait succeeds.
A failure means: clients cannot know when to return, so they retry at once, or the value is wrong and a client that waits as told is refused again.
R2. Rate limit header fields, if you send them
Question: if responses carry RateLimit-Policy or RateLimit, do they agree with what the server enforces?
Steps: read the fields across a short burst.
Expected: the quota the fields advertise is no more generous than what the server enforces, which is this page's own expectation. Section 6 of draft-ietf-httpapi-ratelimit-headers-11, an Internet-Draft and not an RFC, says that if a response contains both the Retry-After and the RateLimit header fields, the Retry-After field value SHOULD NOT reference a point in time earlier than the end of the effective window.
A failure means: clients are told something the server does not enforce. These field names come from draft-ietf-httpapi-ratelimit-headers-11, an Internet-Draft dated 23 May 2026, and may change before any RFC.
COUNTERS ACROSS INSTANCES
D1. Two instances, one count (lab D1)
Question: with more than one instance behind your load balancer, does the limit hold for the whole site?
Steps: send twice your limit plus two from one address.
Expected: exactly your limit succeed in total.
A failure means: each instance keeps its own count, and the real limit is your limit times the number of instances.
D2. Counter store unreachable (lab D2)
Question: when the shared counter store cannot be reached, what happens on each endpoint?
Steps: in staging, stop or block the counter store. Then sign in once with a test account and send a short burst of searches.
Expected: each endpoint does what the worksheet says. This page's advice: sign-in, password reset and one-time code checks fail closed, with 503 and Retry-After, and search fails open to a smaller limit counted in each instance. An alert reaches a named person.
A failure means: sign-in runs with no limit while the store is down, or the whole site returns errors.
THE WAY BACK IN
U1. Waiting (lab U1)
Question: can a customer who was limited sign in again without help?
Steps: with a test account, send wrong passwords up to the account limit, then the right password; wait as Retry-After says; send the right password again.
Expected: 429 with Retry-After, then success after the wait.
A failure means: the customer has to contact you.
U2. A known device while the account is under attack (lab U2)
Question: can someone who knows only the username lock the owner out?
Steps: sign in to a test account from browser A. From other addresses, send wrong passwords past the account limit. Sign in from browser A again.
Expected: browser A signs in. A browser that has never signed in to this account is refused until the window passes.
A failure means: anyone can lock a customer out for as long as they keep sending guesses.
U3. Password reset clears the way (not in the lab)
Question: does a completed password reset let the owner back in?
Steps: limit a test account as in U1, complete a password reset for it, then sign in with the new password.
Expected: whatever your worksheet says. If the reset clears the account's sign-in count, the sign-in succeeds at once.
A failure means: the lockout outlasts the reset, and the only way back is time or your support team.
==== PART C. THE LAB ====
WHAT IT IS
An illustration on one machine. Two versions of a small service with a sign-in route and a search route: a careless version (one fixed one-minute window per address, counted in each process's memory, the address taken from the first X-Forwarded-For entry, and no Retry-After) and a careful version (limits per account, per device, per address and a global ceiling, all held in one shared counter store, sliding windows, and Retry-After on every refusal). Each version runs as two instance processes behind the lab's own round-robin step, so a limit counted per process shows up as numbers. The careful version also has a counter store process, which one scenario stops.
WHAT IT NEEDS
Node.js, and nothing to install. The lab imports only node:child_process, node:crypto, node:http, node:path, node:url, node:assert/strict and node:test, and installs no packages. The outputs below were recorded on Node.js 26.0.0 on macOS. The lab was not run on other versions for this page.
WHAT IT DOES AND DOES NOT DO
Every process listens only on 127.0.0.1, on a port the operating system picks, and the lab sends nothing anywhere else. Each run starts its processes, runs its scenarios and stops every process it started by its process id. No scenario sends more than 39 requests.
Two shortcuts are for the lab only. x-lab-clock carries the time in seconds, so a five-minute window replays in milliseconds; a real service reads its own clock. x-lab-client-address names the address a request stands for, because every lab request really comes from 127.0.0.1; the round-robin step appends it to X-Forwarded-For, in the way a proxy appends the address of the connection it received.
The accounts (customer01 to customer40 at shop.example), their passwords and every address are invented. .example is one of the names RFC 2606 reserves for documentation and examples.
The limits (10 searches per address per minute, 10 sign-in attempts per address per minute, 5 per account or per device in five minutes, a global ceiling of 30 a minute, and 5 per instance while the store is down) are set so that small runs reach them. They are not recommended values.
SET-UP
Create an empty folder, save the eight files below into it under the names shown, and run the commands under RUN IT from that folder.
==== File 1 of 8: counter-store.mjs ====
// counter-store.mjs: the shared counter store for the careful version, run as
// its own process. It keeps, for each key, the times of the requests counted
// inside the key's window. Both instances send every count here, and each
// operation reads and changes its key inside one synchronous function, with
// no await between the read and the write.
import { createServer } from 'node:http'
const hitsByKey = new Map()
// Drops the times that have left the window. A time counts for exactly
// "window" seconds after it was recorded.
function listRecentHits(key, now, window) {
const recent = (hitsByKey.get(key) || []).filter((time) => time > now - window)
hitsByKey.set(key, recent)
return recent
}
// Records one hit if the key is under its limit. When it is not, says how
// many seconds remain until the oldest counted hit leaves the window.
function take(operation) {
const recent = listRecentHits(operation.key, operation.now, operation.window)
if (recent.length >= operation.limit) {
const retryAfter = Math.max(1, Math.ceil(recent[0] + operation.window - operation.now))
return { allowed: false, retryAfter }
}
recent.push(operation.now)
return { allowed: true, remaining: operation.limit - recent.length }
}
function clear(operation) {
hitsByKey.delete(operation.key)
return { cleared: true }
}
function runOperation(operation) {
if (operation.type === 'take') return take(operation)
if (operation.type === 'clear') return clear(operation)
return { error: 'unknown operation' }
}
const server = createServer((request, response) => {
let text = ''
request.on('data', (chunk) => { text = text + chunk })
request.on('end', () => {
const result = runOperation(JSON.parse(text))
response.writeHead(200, { 'content-type': 'application/json' })
response.end(JSON.stringify(result))
})
})
server.listen(0, '127.0.0.1', () => process.send({ port: server.address().port }))
process.on('disconnect', () => process.exit(0))
==== File 2 of 8: careless-limits.mjs ====
// careless-limits.mjs: the careless version's limit. One fixed one-minute
// window per route and address, counted in this process's memory only, so
// every instance keeps its own count. The address is the first entry in
// X-Forwarded-For, which is whatever the client wrote there. A refusal has no
// Retry-After, so the client cannot tell when to come back.
const LIMIT = 10
const WINDOW_SECONDS = 60
const countsByKey = new Map()
export function readCarelessAddress(request) {
const forwarded = String(request.headers['x-forwarded-for'] || '')
return forwarded.split(',')[0].trim()
}
export function checkCarelessLimit(route, address, now) {
const windowStart = Math.floor(now / WINDOW_SECONDS) * WINDOW_SECONDS
const key = route + '|' + address + '|' + windowStart
const count = (countsByKey.get(key) || 0) + 1
countsByKey.set(key, count)
if (count > LIMIT) return { status: 429, retryAfter: null, limit: route + ' per address' }
return null
}
==== File 3 of 8: careful-limits.mjs ====
// careful-limits.mjs: the careful version's limits. Every counter lives in
// the shared counter store, so all instances count together, and each one is
// a sliding window. Every refusal names the limit and carries Retry-After.
// If the store cannot be reached, sign-in fails closed and search falls back
// to a small limit counted in this instance.
import { createHmac, randomBytes } from 'node:crypto'
import { request as httpRequest } from 'node:http'
export const LIMITS = {
searchPerAddress: { limit: 10, window: 60 },
signInPerAddress: { limit: 10, window: 60 },
signInPerAccount: { limit: 5, window: 300 },
signInPerDevice: { limit: 5, window: 300 },
signInGlobal: { limit: 30, window: 60 },
searchFallbackPerInstance: { limit: 5, window: 60 },
}
const STORE_TIMEOUT_MS = 200
const STORE_DOWN_RETRY_SECONDS = 30
// The round-robin step in front of the instances appends the address it saw
// to X-Forwarded-For. It is the only proxy, so the last entry is the one to
// count. Entries before it were written by the client.
export function readCarefulAddress(request) {
const entries = String(request.headers['x-forwarded-for'] || '').split(',')
return entries[entries.length - 1].trim()
}
function callStore(storeUrl, operation) {
return new Promise((resolve, reject) => {
const body = JSON.stringify(operation)
const outgoing = httpRequest(storeUrl + '/op', { method: 'POST', agent: false, headers: { 'content-type': 'application/json' } })
outgoing.setTimeout(STORE_TIMEOUT_MS, () => outgoing.destroy(new Error('counter store timed out')))
outgoing.on('error', reject)
outgoing.on('response', (response) => {
let text = ''
response.on('data', (chunk) => { text = text + chunk })
response.on('end', () => resolve(JSON.parse(text)))
})
outgoing.end(body)
})
}
function refuse(status, retryAfter, limit) {
return { status, retryAfter, limit }
}
async function takeFromStore(storeUrl, key, rule, now, limitName) {
const result = await callStore(storeUrl, { type: 'take', key, now, limit: rule.limit, window: rule.window })
return result.allowed ? null : refuse(429, result.retryAfter, limitName)
}
// ---- Search ----
const localSearchHits = new Map()
// Used only while the store is down: a smaller limit kept in this instance.
// With two instances, 5 each keeps the total near the shared limit of 10.
function checkSearchLocally(address, now) {
const rule = LIMITS.searchFallbackPerInstance
const recent = (localSearchHits.get(address) || []).filter((time) => time > now - rule.window)
localSearchHits.set(address, recent)
if (recent.length >= rule.limit) {
return refuse(429, Math.max(1, Math.ceil(recent[0] + rule.window - now)), 'search fallback per instance')
}
recent.push(now)
return null
}
export async function checkSearchLimit(storeUrl, address, now) {
try {
return await takeFromStore(storeUrl, 'search|address|' + address, LIMITS.searchPerAddress, now, 'search per address')
} catch {
return checkSearchLocally(address, now)
}
}
// ---- Sign-in ----
// A device cookie is issued after a successful sign-in: the login, a random
// nonce and an HMAC of both, so any instance holding the secret can check it.
export function issueDeviceCookie(secret, username) {
const nonce = randomBytes(12).toString('hex')
const signature = createHmac('sha256', secret).update(username + '|' + nonce).digest('hex')
return username + '|' + nonce + '|' + signature
}
export function readDeviceCookie(secret, cookieHeader, username) {
const match = /(?:^|;\s*)device=([^;]+)/.exec(String(cookieHeader || ''))
if (!match) return null
const parts = decodeURIComponent(match[1]).split('|')
if (parts.length !== 3 || parts[0] !== username) return null
const expected = createHmac('sha256', secret).update(parts[0] + '|' + parts[1]).digest('hex')
return parts[2] === expected ? parts[1] : null
}
// The key a sign-in attempt is counted against. A known device has its own
// allowance; every other attempt on the account shares one. The username is
// counted as typed, whether or not it is an account, so a refusal does not
// reveal which accounts exist.
export function chooseAttemptKey(username, deviceNonce) {
if (deviceNonce) return { key: 'sign-in|device|' + deviceNonce, rule: LIMITS.signInPerDevice, name: 'sign-in per device' }
return { key: 'sign-in|account|' + username, rule: LIMITS.signInPerAccount, name: 'sign-in per account' }
}
// Runs before the password check. A known device skips the address limit
// and the global ceiling, which are aimed at unknown clients.
export async function checkSignInLimits(storeUrl, attempt) {
const attemptKey = chooseAttemptKey(attempt.username, attempt.deviceNonce)
const checks = [[attemptKey.key, attemptKey.rule, attemptKey.name]]
if (!attempt.deviceNonce) {
checks.push(['sign-in|address|' + attempt.address, LIMITS.signInPerAddress, 'sign-in per address'])
checks.push(['sign-in|global', LIMITS.signInGlobal, 'sign-in global ceiling'])
}
try {
for (const check of checks) {
const refusal = await takeFromStore(storeUrl, check[0], check[1], attempt.now, check[2])
if (refusal) return refusal
}
return null
} catch {
return refuse(503, STORE_DOWN_RETRY_SECONDS, 'counter store unreachable')
}
}
// A successful sign-in clears the counter it was counted against. If the
// store has just become unreachable, the count runs out with its window.
export async function clearAfterSuccess(storeUrl, username, deviceNonce) {
const attemptKey = chooseAttemptKey(username, deviceNonce)
try {
await callStore(storeUrl, { type: 'clear', key: attemptKey.key })
} catch {
// Nothing to undo: the sign-in itself has already succeeded.
}
}
==== File 4 of 8: app-instance.mjs ====
// app-instance.mjs: one instance of the lab service, run as its own process.
// It has a sign-in route and a search route, limited by the careless or the
// careful version (LAB_VERSION). It listens on 127.0.0.1 only, on a port the
// operating system picks, and tells the process that started it which one.
//
// Lab-only shortcut: the x-lab-clock header carries the time in seconds, so a
// five-minute window replays in milliseconds. A real service reads its own
// clock.
import { createServer } from 'node:http'
import { checkCarelessLimit, readCarelessAddress } from './careless-limits.mjs'
import {
checkSearchLimit, checkSignInLimits, clearAfterSuccess, issueDeviceCookie, readCarefulAddress, readDeviceCookie,
} from './careful-limits.mjs'
const VERSION = process.env.LAB_VERSION
const STORE_URL = process.env.LAB_STORE_URL
const DEVICE_SECRET = process.env.LAB_DEVICE_SECRET
// Invented accounts: customer01@shop.example to customer40@shop.example.
// Each password is lab-pass- and the same two digits. The lab compares plain
// text because nothing here is about how passwords are stored.
function isCorrectPassword(username, password) {
const match = /^customer(\d\d)@shop\.example$/.exec(username)
if (!match || Number(match[1]) < 1 || Number(match[1]) > 40) return false
return password === 'lab-pass-' + match[1]
}
function reply(response, status, body, headers) {
response.writeHead(status, Object.assign({ 'content-type': 'application/json' }, headers || {}))
response.end(JSON.stringify(body))
}
function replyRefused(response, refusal) {
const headers = {}
let message = 'Too many requests.'
if (refusal.retryAfter !== null) {
headers['retry-after'] = String(refusal.retryAfter)
message = 'Too many requests. Try again in ' + refusal.retryAfter + ' seconds.'
}
if (refusal.status === 503) message = 'Sign-in is paused for a moment. Try again in ' + refusal.retryAfter + ' seconds.'
reply(response, refusal.status, { error: message, limit: refusal.limit }, headers)
}
function readBody(request) {
return new Promise((resolve) => {
let text = ''
request.on('data', (chunk) => { text = text + chunk })
request.on('end', () => {
try { resolve(JSON.parse(text)) } catch { resolve({}) }
})
})
}
async function handleSearch(request, response, now) {
const refusal = VERSION === 'careful'
? await checkSearchLimit(STORE_URL, readCarefulAddress(request), now)
: checkCarelessLimit('search', readCarelessAddress(request), now)
if (refusal) return replyRefused(response, refusal)
reply(response, 200, { results: [] })
}
async function handleCarelessSignIn(request, response, now, body) {
const refusal = checkCarelessLimit('sign-in', readCarelessAddress(request), now)
if (refusal) return replyRefused(response, refusal)
if (!isCorrectPassword(body.username, body.password)) return reply(response, 401, { error: 'Email or password is incorrect.' })
reply(response, 200, { signedIn: true })
}
async function handleCarefulSignIn(request, response, now, body) {
const deviceNonce = readDeviceCookie(DEVICE_SECRET, request.headers.cookie, body.username)
const attempt = { username: body.username, address: readCarefulAddress(request), deviceNonce, now }
const refusal = await checkSignInLimits(STORE_URL, attempt)
if (refusal) return replyRefused(response, refusal)
if (!isCorrectPassword(body.username, body.password)) return reply(response, 401, { error: 'Email or password is incorrect.' })
await clearAfterSuccess(STORE_URL, body.username, deviceNonce)
const cookie = 'device=' + encodeURIComponent(issueDeviceCookie(DEVICE_SECRET, body.username)) + '; HttpOnly; Secure; SameSite=Lax'
reply(response, 200, { signedIn: true }, { 'set-cookie': cookie })
}
async function route(request, response) {
const now = Number(request.headers['x-lab-clock'] || 0)
if (request.method === 'GET' && request.url.startsWith('/search')) return handleSearch(request, response, now)
if (request.method === 'POST' && request.url === '/sign-in') {
const body = await readBody(request)
body.username = String(body.username || '')
body.password = String(body.password || '')
if (VERSION === 'careful') return handleCarefulSignIn(request, response, now, body)
return handleCarelessSignIn(request, response, now, body)
}
reply(response, 404, { error: 'Not found.' })
}
const server = createServer((request, response) => { route(request, response) })
server.listen(0, '127.0.0.1', () => process.send({ port: server.address().port }))
process.on('disconnect', () => process.exit(0))
==== File 5 of 8: lab-stack.mjs ====
// lab-stack.mjs: starts one version of the lab. The careful version gets a
// counter store process; both get two instance processes and a round-robin
// step in this process that sends each request to the next instance in turn.
// Every process listens on 127.0.0.1 only, and stop() ends each one by its
// process id.
import { fork } from 'node:child_process'
import { randomBytes } from 'node:crypto'
import { createServer, request as httpRequest } from 'node:http'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
const HERE = path.dirname(fileURLToPath(import.meta.url))
function startProcess(fileName, env) {
return new Promise((resolve, reject) => {
const child = fork(path.join(HERE, fileName), [], { env: Object.assign({}, process.env, env) })
child.once('message', (message) => resolve({ child, url: 'http://127.0.0.1:' + message.port }))
child.once('error', reject)
})
}
function stopProcess(started) {
return new Promise((resolve) => {
if (started.child.exitCode !== null || started.child.signalCode !== null) return resolve()
started.child.once('exit', () => resolve())
process.kill(started.child.pid, 'SIGTERM')
})
}
// Lab-only shortcut: every lab request comes from 127.0.0.1, so the client
// names the address it stands for in x-lab-client-address. The round-robin
// step plays the proxy: it appends that address to X-Forwarded-For, the way
// a proxy appends the address of the connection it received.
function forwardRequest(incoming, outgoingResponse, targetUrl) {
const headers = Object.assign({}, incoming.headers)
const clientAddress = String(headers['x-lab-client-address'] || '127.0.0.1')
delete headers['x-lab-client-address']
headers['x-forwarded-for'] = headers['x-forwarded-for'] ? headers['x-forwarded-for'] + ', ' + clientAddress : clientAddress
const outgoing = httpRequest(targetUrl + incoming.url, { method: incoming.method, headers, agent: false })
outgoing.on('response', (response) => {
outgoingResponse.writeHead(response.statusCode, response.headers)
response.pipe(outgoingResponse)
})
outgoing.on('error', () => {
outgoingResponse.writeHead(502, { 'content-type': 'application/json' })
outgoingResponse.end(JSON.stringify({ error: 'Instance unreachable.' }))
})
incoming.pipe(outgoing)
}
function startRoundRobin(instanceUrls) {
let next = 0
const server = createServer((incoming, outgoingResponse) => {
const target = instanceUrls[next % instanceUrls.length]
next += 1
forwardRequest(incoming, outgoingResponse, target)
})
return new Promise((resolve) => {
server.listen(0, '127.0.0.1', () => resolve({ server, url: 'http://127.0.0.1:' + server.address().port }))
})
}
export async function startStack(version) {
const store = version === 'careful' ? await startProcess('counter-store.mjs', {}) : null
const env = {
LAB_VERSION: version,
LAB_STORE_URL: store ? store.url : '',
LAB_DEVICE_SECRET: randomBytes(32).toString('hex'),
}
const instances = [await startProcess('app-instance.mjs', env), await startProcess('app-instance.mjs', env)]
const roundRobin = await startRoundRobin(instances.map((instance) => instance.url))
return {
url: roundRobin.url,
hasStore: store !== null,
stopStore: async () => { if (store) await stopProcess(store) },
stop: async () => {
await new Promise((resolve) => roundRobin.server.close(resolve))
for (const instance of instances) await stopProcess(instance)
if (store) await stopProcess(store)
},
}
}
==== File 6 of 8: scenarios.mjs ====
// scenarios.mjs: the verification table's checks, as small request runs sent
// one at a time through the round-robin step. Each scenario has its own
// stretch of the lab clock (600 seconds apart) and its own addresses and
// accounts, so no scenario counts against another. None sends more than 39
// requests.
import { request as httpRequest } from 'node:http'
function send(baseUrl, options) {
return new Promise((resolve, reject) => {
const headers = { 'x-lab-client-address': options.address, 'x-lab-clock': String(options.clock) }
if (options.cookie) headers.cookie = options.cookie
if (options.forwardedFor) headers['x-forwarded-for'] = options.forwardedFor
let body = ''
if (options.signIn) {
body = JSON.stringify(options.signIn)
headers['content-type'] = 'application/json'
}
const method = options.signIn ? 'POST' : 'GET'
const target = options.signIn ? '/sign-in' : '/search?q=lab'
const outgoing = httpRequest(baseUrl + target, { method, headers, agent: false })
outgoing.on('error', reject)
outgoing.on('response', (response) => {
let text = ''
response.on('data', (chunk) => { text = text + chunk })
response.on('end', () => resolve({
status: response.statusCode,
retryAfter: response.headers['retry-after'] || null,
setCookie: response.headers['set-cookie'] ? response.headers['set-cookie'][0].split(';')[0] : null,
body: JSON.parse(text),
}))
})
outgoing.end(body)
})
}
function account(number) {
return 'customer' + String(number).padStart(2, '0') + '@shop.example'
}
function rightPassword(number) {
return 'lab-pass-' + String(number).padStart(2, '0')
}
// Counts statuses and keeps the first refusal (429 or 503) with its headers.
function createTally() {
return { statuses: {}, firstRefusal: null }
}
function addToTally(tally, reply) {
tally.statuses[reply.status] = (tally.statuses[reply.status] || 0) + 1
const isRefusal = reply.status === 429 || reply.status === 503
if (isRefusal && !tally.firstRefusal) {
tally.firstRefusal = { status: reply.status, retryAfter: reply.retryAfter, limit: reply.body.limit || null }
}
}
function countAllowed(tally) {
let allowed = 0
for (const status of Object.keys(tally.statuses)) {
if (status !== '429' && status !== '503') allowed += tally.statuses[status]
}
return allowed
}
async function sendAll(baseUrl, list) {
const tally = createTally()
for (const options of list) addToTally(tally, await send(baseUrl, options))
return tally
}
function repeat(count, makeOptions) {
const list = []
for (let index = 0; index < count; index++) list.push(makeOptions(index))
return list
}
// A delay-seconds value, or an HTTP-date in the IMF-fixdate form.
export function isValidRetryAfter(value) {
if (value === null) return false
if (/^[0-9]+$/.test(value)) return true
return /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$/.test(value)
}
// ---- Burst tests ----
async function runShortBurst(baseUrl, start) {
const tally = await sendAll(baseUrl, repeat(12, () => ({ address: '192.0.2.10', clock: start })))
return { tally }
}
async function runSpreadBurst(baseUrl, start) {
const tally = await sendAll(baseUrl, repeat(12, (index) => ({ address: '192.0.2.20', clock: start + index * 5 })))
return { tally }
}
async function runWindowEdge(baseUrl, start) {
const before = repeat(10, () => ({ address: '192.0.2.30', clock: start + 59 }))
const after = repeat(10, () => ({ address: '192.0.2.30', clock: start + 60 }))
const tally = await sendAll(baseUrl, before.concat(after))
return { tally }
}
// ---- One test per dimension ----
async function runOneAccountTwoAddresses(baseUrl, start) {
const list = repeat(12, (index) => ({
address: index % 2 === 0 ? '198.51.100.21' : '198.51.100.22',
clock: start,
signIn: { username: account(3), password: 'wrong-guess-' + index },
}))
return { tally: await sendAll(baseUrl, list) }
}
async function runManyAccountsOneAddress(baseUrl, start) {
const list = repeat(12, (index) => ({
address: '203.0.113.30',
clock: start,
signIn: { username: account(20 + index), password: 'wrong-guess' },
}))
return { tally: await sendAll(baseUrl, list) }
}
async function signInForDeviceCookie(baseUrl, number, address, clock) {
const reply = await send(baseUrl, { address, clock, signIn: { username: account(number), password: rightPassword(number) } })
return reply.setCookie
}
async function runGlobalCeiling(baseUrl, start) {
const cookie = await signInForDeviceCookie(baseUrl, 15, '192.0.2.95', start)
const surge = repeat(36, (index) => ({
address: '203.0.113.' + (100 + Math.floor(index / 2)),
clock: start + 70,
signIn: { username: 'visitor' + index + '@shop.example', password: 'wrong-guess' },
}))
const tally = await sendAll(baseUrl, surge)
const knownDevice = await send(baseUrl, { address: '192.0.2.95', clock: start + 75, cookie, signIn: { username: account(15), password: rightPassword(15) } })
const unknownDevice = await send(baseUrl, { address: '192.0.2.96', clock: start + 76, signIn: { username: account(16), password: rightPassword(16) } })
return { tally, knownDevice, unknownDevice }
}
async function runForwardedHeader(baseUrl, start) {
const tally = await sendAll(baseUrl, repeat(12, (index) => ({
address: '192.0.2.40',
clock: start,
forwardedFor: '198.51.100.' + (100 + index),
})))
return { tally }
}
// ---- Retry-After ----
async function runRetryAfter(baseUrl, start) {
const tally = createTally()
let refusal = null
for (let index = 0; index < 30 && !refusal; index++) {
const reply = await send(baseUrl, { address: '192.0.2.60', clock: start })
addToTally(tally, reply)
if (reply.status === 429) refusal = reply
}
const wait = refusal && isValidRetryAfter(refusal.retryAfter) && /^[0-9]+$/.test(refusal.retryAfter) ? Number(refusal.retryAfter) : 0
const next = await send(baseUrl, { address: '192.0.2.60', clock: start + wait })
return { tally, sentBeforeRefusal: countAllowed(tally), retryAfter: refusal ? refusal.retryAfter : null, wait, next }
}
// ---- Counters across instances ----
async function runTwoInstances(baseUrl, start) {
return { tally: await sendAll(baseUrl, repeat(22, () => ({ address: '192.0.2.50', clock: start }))) }
}
async function runStoreUnreachable(baseUrl, start, stack) {
await stack.stopStore()
const signIn = await send(baseUrl, { address: '192.0.2.70', clock: start, signIn: { username: account(12), password: rightPassword(12) } })
const searches = await sendAll(baseUrl, repeat(12, () => ({ address: '192.0.2.71', clock: start })))
return { hasStore: stack.hasStore, signIn, tally: searches }
}
// ---- Recovery for a real customer ----
async function runWaitThenSignIn(baseUrl, start) {
const typos = repeat(5, (index) => ({ address: '192.0.2.80', clock: start + index * 10, signIn: { username: account(13), password: 'typo-' + index } }))
const tally = await sendAll(baseUrl, typos)
const limited = await send(baseUrl, { address: '192.0.2.80', clock: start + 50, signIn: { username: account(13), password: rightPassword(13) } })
addToTally(tally, limited)
const wait = /^[0-9]+$/.test(String(limited.retryAfter)) ? Number(limited.retryAfter) : 0
const next = await send(baseUrl, { address: '192.0.2.80', clock: start + 50 + wait, signIn: { username: account(13), password: rightPassword(13) } })
return { tally, limited, wait, next }
}
async function runKnownDeviceDuringAttack(baseUrl, start) {
const cookie = await signInForDeviceCookie(baseUrl, 14, '192.0.2.90', start)
const attack = repeat(8, (index) => ({
address: '198.51.100.' + (40 + index),
clock: start + 100,
signIn: { username: account(14), password: 'wrong-guess-' + index },
}))
const tally = await sendAll(baseUrl, attack)
const owner = await send(baseUrl, { address: '192.0.2.90', clock: start + 110, cookie, signIn: { username: account(14), password: rightPassword(14) } })
const ownerNewDevice = await send(baseUrl, { address: '192.0.2.91', clock: start + 111, signIn: { username: account(14), password: rightPassword(14) } })
return { tally, owner, ownerNewDevice }
}
export const SCENARIOS = [
{ id: 'B1', title: 'Short burst just over the limit: 12 searches at one moment from one address', run: runShortBurst },
{ id: 'B2', title: 'The same 12 searches spread across the window, one every 5 seconds', run: runSpreadBurst },
{ id: 'B3', title: 'Window edge: 10 searches 1 second before a minute boundary and 10 on it', run: runWindowEdge },
{ id: 'P1', title: 'One account, two addresses: 12 wrong passwords for customer03', run: runOneAccountTwoAddresses },
{ id: 'P2', title: 'Many accounts, one address: 1 wrong password for each of 12 accounts', run: runManyAccountsOneAddress },
{ id: 'P3', title: 'Global ceiling: 36 wrong passwords from 18 addresses, then two real customers', run: runGlobalCeiling },
{ id: 'P4', title: 'Client-written X-Forwarded-For: 12 searches from one address, each naming another', run: runForwardedHeader },
{ id: 'R1', title: 'Retry-After: search until refused, wait as told, try once more', run: runRetryAfter },
{ id: 'D1', title: 'Two instances: 22 searches at one moment from one address', run: runTwoInstances },
{ id: 'U1', title: 'Recovery by waiting: 5 typos, then the right password, then the wait', run: runWaitThenSignIn },
{ id: 'U2', title: 'Recovery on a known device: 8 wrong passwords from elsewhere, then the owner', run: runKnownDeviceDuringAttack },
{ id: 'D2', title: 'Counter store unreachable: the store process is stopped', run: runStoreUnreachable },
]
export async function runAllScenarios(stack) {
const results = new Map()
for (let index = 0; index < SCENARIOS.length; index++) {
const scenario = SCENARIOS[index]
const start = 600 * (index + 1)
results.set(scenario.id, await scenario.run(stack.url, start, stack))
}
return results
}
export { countAllowed }
==== File 7 of 8: run-lab.mjs ====
// run-lab.mjs: runs every scenario against the careful version and then the
// careless one, and prints what each sent back. Each version runs as its own
// set of processes, started before its scenarios and stopped after them.
import { startStack } from './lab-stack.mjs'
import { countAllowed, isValidRetryAfter, runAllScenarios, SCENARIOS } from './scenarios.mjs'
function describeStatuses(tally) {
const parts = Object.keys(tally.statuses).sort().map((status) => status + ' x' + tally.statuses[status])
return parts.join(', ')
}
function describeReply(reply) {
if (reply.status !== 429 && reply.status !== 503) return String(reply.status)
const retry = reply.retryAfter === null ? 'no Retry-After' : 'Retry-After ' + reply.retryAfter
return reply.status + ' (' + retry + ', limit: ' + reply.body.limit + ')'
}
function describeFirstRefusal(tally) {
const refusal = tally.firstRefusal
if (!refusal) return 'no refusal'
const retry = refusal.retryAfter === null ? 'no Retry-After' : 'Retry-After ' + refusal.retryAfter
return 'first refusal ' + refusal.status + ', ' + retry + ', limit: ' + refusal.limit
}
function describeRetryAfterCheck(result) {
const lines = ['allowed before the first 429: ' + result.sentBeforeRefusal]
if (result.retryAfter === null) {
lines.push('Retry-After: absent, so the client retried at once: ' + result.next.status)
} else {
const form = isValidRetryAfter(result.retryAfter) ? 'valid' : 'not valid'
lines.push('Retry-After: ' + result.retryAfter + ' (' + form + '); after waiting ' + result.wait + ' s: ' + result.next.status)
}
return lines
}
function describeWaitThenSignIn(result) {
const typoStatus = result.tally.statuses['401'] || 0
if (result.limited.status !== 429) {
return ['5 typos: 401 x' + typoStatus + '; right password: ' + describeReply(result.limited) + ', not limited']
}
return [
'5 typos: 401 x' + typoStatus + '; right password: ' + describeReply(result.limited),
'after waiting ' + result.wait + ' s, right password: ' + describeReply(result.next),
]
}
function describeScenario(id, result) {
const lines = []
if (id === 'R1') return describeRetryAfterCheck(result)
if (id === 'U1') return describeWaitThenSignIn(result)
lines.push('statuses: ' + describeStatuses(result.tally) + '; allowed ' + countAllowed(result.tally) + '; ' + describeFirstRefusal(result.tally))
if (id === 'P3') {
lines.push('customer on a known device: ' + describeReply(result.knownDevice) + '; customer on a new device: ' + describeReply(result.unknownDevice))
}
if (id === 'U2') {
lines.push('owner on the known device: ' + describeReply(result.owner) + '; owner on a new device: ' + describeReply(result.ownerNewDevice))
}
if (id === 'D2') {
lines.unshift('sign-in with the right password: ' + describeReply(result.signIn) + '; then 12 searches:')
if (!result.hasStore) lines.unshift('no counter store in this version: each instance counts alone, as before')
}
return lines
}
async function runVersion(version) {
const stack = await startStack(version)
try {
return await runAllScenarios(stack)
} finally {
await stack.stop()
}
}
console.log('Rate-limit lab, Node.js ' + process.version)
const careful = await runVersion('careful')
const careless = await runVersion('careless')
for (const scenario of SCENARIOS) {
console.log('')
console.log(scenario.id + ' ' + scenario.title)
for (const line of describeScenario(scenario.id, careful.get(scenario.id))) console.log(' careful: ' + line)
for (const line of describeScenario(scenario.id, careless.get(scenario.id))) console.log(' careless: ' + line)
}
==== File 8 of 8: rate-limit.test.mjs ====
// rate-limit.test.mjs: a regression test for the limits. It passes on the
// careful version, the default, and fails on LAB_VERSION=careless. Keep a
// test shaped like this in your own suite, pointed at staging with lowered
// limits, so a change that drops a limit fails the build.
import assert from 'node:assert/strict'
import { after, before, test } from 'node:test'
import { startStack } from './lab-stack.mjs'
import { countAllowed, isValidRetryAfter, runAllScenarios } from './scenarios.mjs'
const version = process.env.LAB_VERSION || 'careful'
let stack
let results
before(async () => {
stack = await startStack(version)
results = await runAllScenarios(stack)
})
after(async () => {
await stack.stop()
})
function allowed(id) {
return countAllowed(results.get(id).tally)
}
test('B1 a short burst stops at the limit of 10', () => {
assert.equal(allowed('B1'), 10)
})
test('B2 the same burst spread across the window still stops at 10', () => {
assert.equal(allowed('B2'), 10)
})
test('B3 a window edge does not let a second 10 through', () => {
assert.equal(allowed('B3'), 10)
})
test('P1 one account tried from two addresses reaches the password check 5 times', () => {
assert.equal(allowed('P1'), 5)
})
test('P2 one address trying many accounts reaches the password check 10 times', () => {
assert.equal(allowed('P2'), 10)
})
test('P3 the global ceiling holds and a known device still signs in', () => {
assert.equal(allowed('P3'), 30)
assert.equal(results.get('P3').knownDevice.status, 200)
})
test('P4 a client-written X-Forwarded-For does not reset the count', () => {
assert.equal(allowed('P4'), 10)
})
test('R1 every 429 carries a valid Retry-After, and waiting that long works', () => {
const result = results.get('R1')
assert.ok(isValidRetryAfter(result.retryAfter), 'Retry-After: ' + result.retryAfter)
assert.equal(result.next.status, 200)
})
test('D1 two instances share one count', () => {
assert.equal(allowed('D1'), 10)
})
test('U1 a customer limited by typos signs in after waiting the Retry-After', () => {
const result = results.get('U1')
assert.equal(result.limited.status, 429)
assert.ok(isValidRetryAfter(result.limited.retryAfter))
assert.equal(result.next.status, 200)
})
test('U2 guesses from elsewhere stop at 5 and the owner on a known device signs in', () => {
assert.equal(allowed('U2'), 5)
assert.equal(results.get('U2').owner.status, 200)
})
test('D2 with the store unreachable, sign-in fails closed and search keeps a cap', () => {
const result = results.get('D2')
assert.equal(result.signIn.status, 503)
assert.ok(isValidRetryAfter(result.signIn.retryAfter))
assert.equal(countAllowed(result.tally), 10)
})
==== RUN IT ====
node run-lab.mjs
node --test rate-limit.test.mjs
LAB_VERSION=careless node --test rate-limit.test.mjs
==== PART D. OUTPUT OF node run-lab.mjs (Node.js v26.0.0, macOS) ====
Rate-limit lab, Node.js v26.0.0
B1 Short burst just over the limit: 12 searches at one moment from one address
careful: statuses: 200 x10, 429 x2; allowed 10; first refusal 429, Retry-After 60, limit: search per address
careless: statuses: 200 x12; allowed 12; no refusal
B2 The same 12 searches spread across the window, one every 5 seconds
careful: statuses: 200 x10, 429 x2; allowed 10; first refusal 429, Retry-After 10, limit: search per address
careless: statuses: 200 x12; allowed 12; no refusal
B3 Window edge: 10 searches 1 second before a minute boundary and 10 on it
careful: statuses: 200 x10, 429 x10; allowed 10; first refusal 429, Retry-After 59, limit: search per address
careless: statuses: 200 x20; allowed 20; no refusal
P1 One account, two addresses: 12 wrong passwords for customer03
careful: statuses: 401 x5, 429 x7; allowed 5; first refusal 429, Retry-After 300, limit: sign-in per account
careless: statuses: 401 x12; allowed 12; no refusal
P2 Many accounts, one address: 1 wrong password for each of 12 accounts
careful: statuses: 401 x10, 429 x2; allowed 10; first refusal 429, Retry-After 60, limit: sign-in per address
careless: statuses: 401 x12; allowed 12; no refusal
P3 Global ceiling: 36 wrong passwords from 18 addresses, then two real customers
careful: statuses: 401 x30, 429 x6; allowed 30; first refusal 429, Retry-After 60, limit: sign-in global ceiling
careful: customer on a known device: 200; customer on a new device: 429 (Retry-After 54, limit: sign-in global ceiling)
careless: statuses: 401 x36; allowed 36; no refusal
careless: customer on a known device: 200; customer on a new device: 200
P4 Client-written X-Forwarded-For: 12 searches from one address, each naming another
careful: statuses: 200 x10, 429 x2; allowed 10; first refusal 429, Retry-After 60, limit: search per address
careless: statuses: 200 x12; allowed 12; no refusal
R1 Retry-After: search until refused, wait as told, try once more
careful: allowed before the first 429: 10
careful: Retry-After: 60 (valid); after waiting 60 s: 200
careless: allowed before the first 429: 20
careless: Retry-After: absent, so the client retried at once: 429
D1 Two instances: 22 searches at one moment from one address
careful: statuses: 200 x10, 429 x12; allowed 10; first refusal 429, Retry-After 60, limit: search per address
careless: statuses: 200 x20, 429 x2; allowed 20; first refusal 429, no Retry-After, limit: search per address
U1 Recovery by waiting: 5 typos, then the right password, then the wait
careful: 5 typos: 401 x5; right password: 429 (Retry-After 250, limit: sign-in per account)
careful: after waiting 250 s, right password: 200
careless: 5 typos: 401 x5; right password: 200, not limited
U2 Recovery on a known device: 8 wrong passwords from elsewhere, then the owner
careful: statuses: 401 x5, 429 x3; allowed 5; first refusal 429, Retry-After 300, limit: sign-in per account
careful: owner on the known device: 200; owner on a new device: 429 (Retry-After 289, limit: sign-in per account)
careless: statuses: 401 x8; allowed 8; no refusal
careless: owner on the known device: 200; owner on a new device: 200
D2 Counter store unreachable: the store process is stopped
careful: sign-in with the right password: 503 (Retry-After 30, limit: counter store unreachable); then 12 searches:
careful: statuses: 200 x10, 429 x2; allowed 10; first refusal 429, Retry-After 60, limit: search fallback per instance
careless: no counter store in this version: each instance counts alone, as before
careless: sign-in with the right password: 200; then 12 searches:
careless: statuses: 200 x12; allowed 12; no refusal
==== PART E. OUTPUT OF node --test rate-limit.test.mjs (careful version) ====
✔ B1 a short burst stops at the limit of 10 (475.958167ms)
✔ B2 the same burst spread across the window still stops at 10 (0.086209ms)
✔ B3 a window edge does not let a second 10 through (0.047ms)
✔ P1 one account tried from two addresses reaches the password check 5 times (0.048292ms)
✔ P2 one address trying many accounts reaches the password check 10 times (0.055875ms)
✔ P3 the global ceiling holds and a known device still signs in (0.037042ms)
✔ P4 a client-written X-Forwarded-For does not reset the count (0.048792ms)
✔ R1 every 429 carries a valid Retry-After, and waiting that long works (0.073ms)
✔ D1 two instances share one count (0.060959ms)
✔ U1 a customer limited by typos signs in after waiting the Retry-After (0.077375ms)
✔ U2 guesses from elsewhere stop at 5 and the owner on a known device signs in (0.0435ms)
✔ D2 with the store unreachable, sign-in fails closed and search keeps a cap (0.035ms)
ℹ tests 12
ℹ suites 0
ℹ pass 12
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 585.751542
==== PART F. OUTPUT OF LAB_VERSION=careless node --test rate-limit.test.mjs ====
✖ B1 a short burst stops at the limit of 10 (295.270291ms)
✖ B2 the same burst spread across the window still stops at 10 (0.434666ms)
✖ B3 a window edge does not let a second 10 through (0.102458ms)
✖ P1 one account tried from two addresses reaches the password check 5 times (0.07575ms)
✖ P2 one address trying many accounts reaches the password check 10 times (0.070667ms)
✖ P3 the global ceiling holds and a known device still signs in (0.074292ms)
✖ P4 a client-written X-Forwarded-For does not reset the count (0.057334ms)
✖ R1 every 429 carries a valid Retry-After, and waiting that long works (0.087917ms)
✖ D1 two instances share one count (0.082083ms)
✖ U1 a customer limited by typos signs in after waiting the Retry-After (0.0905ms)
✖ U2 guesses from elsewhere stop at 5 and the owner on a known device signs in (0.071959ms)
✖ D2 with the store unreachable, sign-in fails closed and search keeps a cap (0.057334ms)
ℹ tests 12
ℹ suites 0
ℹ pass 0
ℹ fail 12
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 411.141792
✖ failing tests:
test at rate-limit.test.mjs:27:1
✖ B1 a short burst stops at the limit of 10 (295.270291ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
12 !== 10
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:31:1
✖ B2 the same burst spread across the window still stops at 10 (0.434666ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
12 !== 10
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:35:1
✖ B3 a window edge does not let a second 10 through (0.102458ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
20 !== 10
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:39:1
✖ P1 one account tried from two addresses reaches the password check 5 times (0.07575ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
12 !== 5
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:43:1
✖ P2 one address trying many accounts reaches the password check 10 times (0.070667ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
12 !== 10
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:47:1
✖ P3 the global ceiling holds and a known device still signs in (0.074292ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
36 !== 30
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:52:1
✖ P4 a client-written X-Forwarded-For does not reset the count (0.057334ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
12 !== 10
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:56:1
✖ R1 every 429 carries a valid Retry-After, and waiting that long works (0.087917ms)
AssertionError [ERR_ASSERTION]: Retry-After: null
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:62:1
✖ D1 two instances share one count (0.082083ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
20 !== 10
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:66:1
✖ U1 a customer limited by typos signs in after waiting the Retry-After (0.0905ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
200 !== 429
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:73:1
✖ U2 guesses from elsewhere stop at 5 and the owner on a known device signs in (0.071959ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
8 !== 5
(cut here: the stack trace, which shows local file paths, and the error object fields)
test at rate-limit.test.mjs:78:1
✖ D2 with the store unreachable, sign-in fails closed and search keeps a cap (0.057334ms)
AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
200 !== 503
(cut here: the stack trace, which shows local file paths, and the error object fields)
Exit codes, as the shell reported them after each command:
node run-lab.mjs: exit code 0
node --test rate-limit.test.mjs: exit code 0
LAB_VERSION=careless node --test rate-limit.test.mjs: exit code 1
==== PART G. READING THE OUTPUT ====
statuses: every status the scenario's requests got, with counts. 401 is a wrong password that reached the password check.
allowed: requests that were not refused with 429 or 503. On sign-in, that is how many guesses reached the password check.
first refusal: the status, Retry-After and limit name of the first request a limit refused.
What the runs show
Bursts (B1 to B3). The careful version allowed 10 every time. The careless version allowed 12, 12 and 20: each instance counted only the requests it received, and at the minute boundary the fixed window started again. The careless code does use a fixed window (File 2: checkCarelessLimit puts the start of the current minute in each counter's key), but the 20 in B3 does not isolate it, because each instance received only 5 searches on each side of the boundary, 10 in all, which a limit of 10 allows with any kind of window. No scenario in this run isolates the fixed window, and seeing it in the numbers would take a larger burst or a run with a single instance.
Dimensions (P1 to P4). The account limit stopped guessing on customer03 at 5 although the attempts came from two addresses, and the address limit stopped one address at 10 across 12 accounts. At the global ceiling, a customer on a browser that had signed in before still got in, and one on a new browser was refused with Retry-After 54. A client-written X-Forwarded-For did not reset the careful count, and reset the careless one on every request. The careless code does read the client's entry (File 2: readCarelessAddress returns the first X-Forwarded-For entry), but the 12 in P4 does not isolate that, because each instance received only 6 of the 12 searches, under its limit of 10, as in B1, where no header was written and the careless version also allowed 12. No scenario in this run isolates it, and seeing it in the numbers would take a larger burst or a run with a single instance.
Retry-After (R1). The careful version said 60, and the request sent 60 seconds later succeeded. The careless version allowed 20 before its first 429, sent no Retry-After, and the client's immediate retry was refused.
Instances (D1 and D2). Counted in each process, the limit of 10 became 20. With the store stopped, the careful version refused sign-in with 503 and Retry-After 30, and search fell back to 5 per instance, 10 in total.
The way back in (U1 and U2). After five typos the customer was refused with Retry-After 250 and signed in after the wait. While someone else sent wrong passwords for customer14, the owner signed in from the browser that had signed in before, and was refused for 289 seconds on a new one.
Regression test. 12 of 12 passed on the careful version and 12 of 12 failed on the careless one. The test runner sets the exit code to 1 when any test fails, so the same file in a build pipeline fails the build.
==== USING IT ON YOUR OWN SERVICE ====
1. Fill in Part A for each endpoint, from your own traffic, and keep it with your security documentation.
2. Turn the Part B rows you use into a test shaped like rate-limit.test.mjs, pointed at staging with test accounts and limits lowered so that a handful of requests reach them.
3. Drop the two lab headers. Your service takes the time from its own clock and the client address from the connection, or from the entry your own proxy adds.
4. Run the test on every build, so a change that drops a limit, a Retry-After or the shared store fails before it reaches production.What rate limiting is, and what it protects
Rate limiting is a rule that counts something a client does, such as requests, failed sign-ins or units of work, against a key, such as an account or an IP address, over a window of time, and decides what happens when the count reaches a limit.
MITRE catalogues the missing control as CWE-799, Improper Control of Interaction Frequency: the product does not properly limit the number or frequency of interactions that it has with an actor, such as the number of incoming requests. HTTP has a status code for the refusal.
RFC 6585, published in April 2012, says the 429 Too Many Requests status code indicates that the user has sent too many requests in a given amount of time, and calls that "rate limiting".
A limit protects one of three things, and which one it protects decides how it should be built.
- Accounts from guessing. Each sign-in attempt or one-time code check is a guess at a secret, so the limit caps the guesses one account can take. For passwords, NIST SP 800-63B-4 says verifiers SHALL implement a rate-limiting mechanism that effectively limits the number of failed authentication attempts that can be made on the subscriber account.
- A budget from a costly endpoint. A password reset that sends a text message, an export that runs for a minute or a feature that calls a paid service costs money or server time on every request. OWASP's API4:2023 Unrestricted Resource Consumption notes that some resources are paid for per request, such as emails, SMS and phone calls.
- Everyone else from one heavy user. A search page or a public API serves many customers from shared capacity, and one script sending requests as fast as it can slows the page for all of them.
What the standards ask for
ASVS 5.0 requirement 2.4.1, at Level 2, asks for anti-automation controls against excessive calls to application functions that could lead to data exfiltration, garbage-data creation, quota exhaustion, rate-limit breaches, denial-of-service, or overuse of costly resources. Requirement 2.4.2, at Level 3, asks that business logic flows require realistic human timing, preventing excessively rapid transaction submissions.
API4:2023 recommends a limit on how often a client can interact with the API within a defined timeframe, says rate limiting should be fine tuned based on the business needs, and says some API endpoints might require stricter policies.
Five neighbouring topics have guides of their own. The credential stuffing guide covers passwords leaked from other sites being replayed on your login, and how to spot that pattern in your logs. The MFA security guide covers second factors, push prompts and recovery. The authentication failures guide covers what each sign-in flow gives away, such as which email addresses have accounts.
The API security guide covers the wider API surface. The web application firewall guide covers what a WAF does and does not do at the edge. This page covers the limit itself as a design.
Rate limit design: what is counted, and against which key
A limit has four parts: what it counts, the key it counts against, the window, and what happens at the limit.
The specification of the 429 status code leaves the first two to you. RFC 6585 says it does not define how the origin server identifies the user, nor how it counts requests. Its examples are counts per resource, across the entire server or even among a set of servers, with the user identified by authentication credentials or a stateful cookie.
Count the thing that costs you. For sign-in that is attempts on an account, because each one is a guess. For a costly endpoint, a request is a poor unit when one request can carry many operations. API4:2023 lists the number of operations performed in a single API client request, giving GraphQL batching as its example, among the limits that make an API vulnerable when they are missing or set inappropriately.
Its second attack scenario shows a traditional rate limit on a GraphQL endpoint bypassed by sending many upload operations in one request.
Cloudflare documents a complexity-based option, which it offers only to some customers, in which the origin server returns a score for the cost of each request and the rule enforces a maximum total score per client over a period.
Each key catches something the others miss, and each has a weakness the others cover.
- Account: the username or email address as typed. It follows the target however many addresses the attempts come from. The OWASP Authentication Cheat Sheet says the counter of failed logins should be associated with the account itself, rather than the source IP address, to prevent an attacker making login attempts from a large number of different IP addresses. The weakness is that anyone who knows a customer's username can spend that customer's allowance. The same cheat sheet says that when designing an account lockout system, care must be taken to prevent it from being used to cause a denial of service by locking out other users' accounts.
- IP address: catches one source trying many accounts, which an account limit does not see. It is a weak identity in both directions. Many people can share one address: Cloudflare's rate limiting documentation describes a counting option, offered on some plans, for situations such as requests under NAT sharing the same IP address. One attacker can use many: the OWASP Credential Stuffing Prevention Cheat Sheet says distributing requests across a large volume of unique IP addresses may defeat both IP block-lists and rate limiting, because the volume from each address may stay relatively low.
- Device: a browser that has signed in to this account before. OWASP's community page "Slow Down Online Guessing Attacks with Device Cookies" describes issuing a signed device cookie after each successful sign-in, so the server can tell known clients from unknown ones, lock out all unknown clients for one user for a while, and lock out a known client on its own. It says locking out an account and IP address pair is better for denial-of-service issues but has security downsides: attacks from botnets and attacks through proxies can be effective.
- Global ceiling: everything on the route at once. It catches a run spread so thin that no account, address or device reaches its own limit. Because it counts everyone, reaching it refuses real customers too, so pair it with an exemption for known devices, or a challenge, rather than a flat refusal for all.
Behind a load balancer or a CDN, the connection your application sees comes from the proxy, and the client's address arrives in a header. RFC 7239, which defines the Forwarded header, says that header cannot be relied upon to be correct, as it may be modified, whether mistakenly or for malicious reasons, by every node on the way to the server, including the client making the request.
It describes verifying proxies and treating them as trusted as one approach, and says that approach has at least two weaknesses: the chain of addresses listed before the request came to the proxy cannot be trusted, and unless the communication between proxies and the endpoint is secured, the data can be modified by an attacker with access to the network.
nginx shows how a proxy fills the older X-Forwarded-For header. Its proxy module's $proxy_add_x_forwarded_for variable is the X-Forwarded-For client request header with the $remote_addr variable appended to it, separated by a comma, or $remote_addr alone when the request has no X-Forwarded-For. Its realip module replaces the client address only when the connection comes from an address set as trusted, which its documentation describes as addresses known to send correct replacement addresses.
With recursive search off, the replacement is the last address in the header; with it on, the last address that is not trusted.
So read the entry your own proxy added, not the first one. In the lab, a burst that wrote a different address into X-Forwarded-For on every request got all 12 searches through the careless version, which reads the first entry, and stopped at 10 on the careful version, which reads the entry its own proxy step added.
The careless code does read the client's entry (readCarelessAddress in careless-limits.mjs returns the first one), but in this run its count of 12 does not isolate that flaw: the lab runs each version as two instances, each careless instance keeps its own count, and each received only 6 of the 12 searches, under its limit of 10.
No scenario in this run isolates it, and seeing it in the numbers would take a larger burst or a run with a single instance.
Login rate limiting: sign-in, one-time codes and password resets
Authentication endpoints get the strictest limits.
API2:2023 says anti-brute force mechanisms on authentication endpoints should be stricter than the regular rate limiting on the API, and that credential recovery and forgot-password endpoints should be treated as login endpoints for brute force, rate limiting and lockout protections. ASVS 5.0 requirement 6.3.1, at Level 1, asks that controls against attacks such as credential stuffing and password brute force are implemented according to the application's security documentation.
Requirement 6.1.1, also at Level 1, asks that the documentation makes clear how rate limiting and similar controls are configured and how they prevent malicious account lockout.
NIST SP 800-63B-4, published in July 2025 and focused on authentication to government information systems, gives a number. Section 3.2.2 says that, unless an authenticator's own description says otherwise, the verifier SHALL limit consecutive failed attempts using a specific authenticator on a single account to no more than 100 by disabling that authenticator.
It says 100 is an upper bound that agencies MAY lower, and that after a successful authentication the verifier SHOULD disregard earlier failed attempts for the authenticators used.
That is a ceiling for one authenticator on one account, not a setting for a shop's login form. The worksheet leaves your number to your traffic.
One-time codes need a count that a resend does not reset
A short code has far fewer possible values than a good password. NIST says its limit of 100 was chosen to balance the likelihood of a correct guess, giving the example of 100 attempts against a six-digit decimal OTP, against the potential need for account recovery when the limit is exceeded.
For out-of-band authentication secrets shorter than 64 bits, section 3.1.3.2 says the verifier SHALL limit the total number of consecutive failed attempts on the account, and that generating a new authentication secret SHALL NOT reset the failed authentication count.
ASVS 5.0 requirement 6.6.3, at Level 2, asks that a code-based out-of-band mechanism is protected against brute force attacks by using rate limiting.
A "send a new code" button that starts the count again gives a guesser a fresh allowance with every press. Count wrong codes against the pending sign-in and the account, and keep the count when a new code is sent.
Password reset requests protect an inbox and a bill
The OWASP Forgot Password Cheat Sheet asks for protection against excessive automated submissions, such as rate limiting on a per-account basis, requiring a CAPTCHA or other controls, because otherwise an attacker could flood the user's intake system, such as an email inbox or SMS, with useless requests.
It also says accounts should not be locked out in response to a forgotten password attack. Count the email address or phone number as typed, whether or not it has an account, so a refusal does not reveal which addresses are registered.
Windows and algorithms: what a real customer notices
The window and the way it is counted decide what a limit feels like from the other side.
The descriptions below are this page's own, in plain terms.
- Fixed window: one counter per key per calendar minute or hour, reset when it turns over. It is simple and cheap. A customer refused at 10:00:58 is free two seconds later, and a client that sends a full allowance just before the boundary and another just after gets twice the limit in a few seconds.
- Sliding window: each request counts for exactly one window length after it arrives, so the count is always "the last 60 seconds". A refused client waits until its oldest counted request ages out, which is the figure to send in Retry-After. Kept as a list of times per key, as the lab does, it costs memory per request. An estimate that weighs the previous window's count against the current one needs two counters.
- Token bucket: each key has a bucket of tokens that refills at a steady rate up to a maximum, and each request spends one. It allows a burst up to the bucket size and then a steady rate, which suits a person who opens several pages at once and then reads.
- Leaky bucket: requests leave at a steady rate, and a burst waits in a queue of limited size. nginx's limit_req module says its limitation is done using the "leaky bucket" method. Requests over the configured rate are delayed until their number exceeds the maximum burst size, at which point the request is terminated with an error, and the nodelay parameter turns the delay off.
What matters more than the algorithm's name
Two things decide how a real customer experiences a limit. A refusal should end at a time the server can state, and a burst of normal use, such as a page that fires five searches as it loads, should fit inside the allowance. In the lab, 10 searches a second before a minute boundary and 10 more on it all passed the careless version's fixed window.
The careful version's sliding window refused the second 10 and told the client to come back in 59 seconds. The careless code does use a fixed window (checkCarelessLimit in careless-limits.mjs puts the start of the current minute in each counter's key), but in this run its count of 20 does not isolate that flaw: the lab runs each version as two instances, each careless instance keeps its own count, and each received only 5 searches on each side of the boundary, 10 in all, which a limit of 10 allows with any kind of window.
No scenario in this run isolates it, and seeing it in the numbers would take a larger burst or a run with a single instance.
429 and Retry-After: what the server answers at the limit
RFC 6585 sets out what a 429 response carries.
Its representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request. Responses with the 429 status code MUST NOT be stored by a cache. Its security considerations add that when a server is under attack, or receiving a very large number of requests from a single party, responding to each with 429 consumes resources, so servers are not required to use 429, and when limiting resource usage it may be more appropriate to just drop connections or take other steps.
Retry-After itself is defined in RFC 9110. Servers send it to indicate how long the user agent ought to wait before making a follow-up request. Its value is either an HTTP-date or a number of seconds to delay after receiving the response, and a delay is a non-negative decimal integer.
A sender that generates an HTTP-date MUST use the IMF-fixdate format, such as Fri, 31 Dec 1999 23:59:59 GMT. RFC 9110's Retry-After section (10.2.3) names two kinds of response: with 503 Service Unavailable it indicates how long the service is expected to be unavailable to the client, and with any 3xx redirect, the minimum time to wait before issuing the redirected request.
Section 15.5.14 adds that a server SHOULD generate Retry-After with a 413 Content Too Large response when the condition is temporary. Its use with 429 comes from RFC 6585.
Defaults differ by product, so check what yours sends. nginx's limit_req_status directive, which sets the status code returned to rejected requests, defaults to 503. Cloudflare's rate limiting rules return 429 Too many requests by default when the action is Block, and let you set a value between 400 and 499 instead.
What a good refusal tells the client
A good refusal answers three questions for the person or program that gets it: which limit was reached, when to try again, and what else works. Every refusal from the lab's careful version names its limit in the body and sends Retry-After as whole seconds. NIST SP 800-63B-4's usability considerations say the same for people: for rate limiting, inform users how long they have to wait until the next attempt.
A well-behaved client reads Retry-After, waits at least that long and then tries once, instead of retrying at once. Your own scripts, integrations and mobile app should behave that way, and the verification table checks that the server's figure is true. In the lab, the request sent after waiting the careful version's 60 seconds succeeded. Against the careless version, which sent no Retry-After, an immediate retry was refused again.
The RateLimit header fields are still a draft
Telling clients how much quota is left before they reach the limit is the job of a separate pair of headers. An Internet-Draft from the IETF's HTTPAPI working group, RateLimit header fields for HTTP, notes that many different rate-limit headers are used on the web, with different meanings attached to the same names, and sets out to standardise them.
It defines a RateLimit-Policy field for a quota policy and a RateLimit field for the quota currently available.
It says that if a response contains both RateLimit and Retry-After, Retry-After MUST take precedence, and that clients MUST NOT assume that a positive available quota means further requests will be served.
When this page was reviewed on 14 November 2026, the IETF Datatracker listed revision 11, draft-ietf-httpapi-ratelimit-headers-11, dated 23 May 2026, as an active working group document with no RFC number and no newer revision. That revision gives its own expiry date as 24 November 2026, so check the Datatracker for the current revision and status before you rely on it.
The draft's own boilerplate says Internet-Drafts may be updated, replaced or obsoleted by other documents at any time, and that it is inappropriate to cite them other than as work in progress. Use the field names if they help your clients, and expect them to change.
Distributed rate limiting: where the counter lives
A counter kept in one server's memory counts only what that server saw.
Behind a load balancer with two instances, each instance allows the full limit, so the site allows twice the figure in the worksheet. In the lab, 22 searches from one address at one moment got 20 answers from the careless version, 10 from each instance, and 10 from the careful version, whose instances share one counter store.
A shared store fixes the arithmetic only if each check and count happens as one step. If two instances both read 9, both allow the request and both write 10, the limit has leaked. Redis documents a rate limiter pattern on its INCR command page, with examples that limit API calls to ten requests per second per IP address.
The first keeps one counter per address per second, incremented with INCR and given an expiry with EXPIRE inside a MULTI and EXEC block, so both happen on every call. The page points out a race condition in its second, single-counter version: if the client performs the INCR but not the EXPIRE, the key is leaked until the same address is seen again.
One fix it gives is to send the INCR and its EXPIRE as one Lua script with the EVAL command.
Edge services face the same question at a larger scale. Cloudflare's documentation says it does not support global rate limiting counters across its entire network: each data centre keeps its own counters, except that data centres associated with the same geographical location share them.
It also says its rate limiting rules are not designed to allow a precise number of requests to reach the origin server, because there may be a delay of up to a few seconds between detecting a request and updating counters. nginx keeps limit_req state in a shared memory zone, and its documentation lists a sync parameter, which synchronises that zone, as part of its commercial subscription.
When the counter store is down: fail open or fail closed
A shared store is one more thing that can fail, and the limiter needs a decision for that moment, made in advance for each endpoint.
None of the sources on this page prescribes one, so what follows is this page's advice.
- Fail closed where a missing limit hands out guesses: sign-in, one-time code checks and password reset requests. Refuse with 503 and a short Retry-After, and tell the person plainly that sign-in is paused for a moment.
- Fail open where a short gap costs little and an outage costs a lot: search, browsing, a public catalogue. Fall back to a smaller limit counted in each instance, set to the shared limit divided by the number of instances, so the total stays near the worksheet's figure.
- Give every call to the store a short timeout, so a slow store becomes a decision rather than a queue of waiting requests. The lab uses 200 milliseconds.
- Alert a named person when a fallback is in use, and count how often it happens.
Why 503 fits the closed case
RFC 9110 says the 503 status code indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay, and that the server MAY send Retry-After to suggest how long the client should wait. A 429 would tell the person they had sent too many requests, which is not what happened.
In the lab, with the store process stopped, the careful version refused a correct sign-in with 503 and Retry-After 30, and let 10 of 12 searches through on the fallback of 5 per instance. The careless version had no store to lose, because it never shared a count, and went on letting each instance count alone.
How a limited customer gets back in without calling support
Sooner or later a limit refuses a real customer: a morning of typos, an office behind one address, a script of their own.
The design question is what they do next, and the answer should not be "ring us".
- Tell them when. A refusal with Retry-After and a message that names the time lets a person wait instead of trying again. In the lab, a customer who mistyped five times was refused for 250 seconds and signed in when the time was up.
- Let known devices through. With a device allowance, someone who knows only the username cannot lock the owner out of a browser the owner has used before. In the lab, eight wrong passwords from eight other addresses used up customer14's shared allowance after five, and the owner signed in from their usual browser 10 seconds later. The same password from a new browser was refused for 289 seconds.
- Offer a route that proves something else. The OWASP Authentication Cheat Sheet says care must be taken to prevent a lockout system from being used to lock out other users' accounts, and that one way this could be performed is to allow the use of the forgotten password functionality to log in, even if the account is locked out. If a completed password reset clears the account's sign-in count in your design, say so in the refusal message.
- Clear the count on success, and keep every refusal temporary. NIST SP 800-63B-4 says that after a successful authentication the verifier SHOULD disregard earlier failed attempts for the authenticators used. On mitigating credential stuffing traffic from an IP address, the OWASP Credential Stuffing Prevention Cheat Sheet says mitigations, especially blocking an IP address, should be temporary, and that processes should be in place to remove an IP address from a mitigated state as abuse declines or stops.
Testing rate limits on staging with a few dozen requests
A rate limit test asks whether the limit exists, counts the right key, answers correctly and lets people back in.
None of that needs volume. The verification table in the asset gives each check as a question, the steps, the expected result and what a failure means, and no row sends more than a few dozen requests. Run them on staging with test accounts and limits lowered so a handful of requests reach them.
WSTG-ATHN-03, OWASP's test for weak lockout mechanisms, notes that testing a lockout needs access to an account you are willing or can afford to lock.
These are not load tests. Load, volumetric and denial-of-service testing measures how much a system can take, and it is separate work for a load-testing specialist, with your host's written approval. Do not run these checks against a system you do not own or are not authorised in writing to test.
Keep the checks once they pass. The lab's regression test runs its scenarios on Node.js's test runner, the node:test module, which the Node.js documentation marks stable from version 20.0.0 and which sets the exit code to 1 when any test fails, so a build that runs it fails when a change drops a limit.
What the lab is, and what it showed
The lab is an illustration written for this page. It runs on one machine and measures nothing about capacity, speed or load: its numbers are counts of allowed and refused requests. A small service with a sign-in route and a search route runs in two versions.
The careless version keeps one fixed one-minute window per address in each process's memory, reads the address from the first X-Forwarded-For entry and sends no Retry-After. The careful version counts per account, per device and per address under a global ceiling, in a shared counter store, with sliding windows and Retry-After on every refusal.
Each version runs as two instance processes behind the lab's own round-robin step. Every process listens only on 127.0.0.1, on a port the operating system assigns because the lab asks for port 0.
The lab imports only node:child_process, node:crypto, node:http, node:path, node:url, node:assert/strict and node:test, and installs no packages. Its accounts and addresses are invented, with the accounts under .example, a name RFC 2606 reserves for documentation and examples.
On Node.js 26.0.0 on macOS, twelve scenarios ran against each version. The careful version held each limit at its number: 10 for a burst, a spread burst and the window edge, 5 for one account tried from two addresses, 30 at the global ceiling, and 10 across two instances.
The careless version allowed 12, 12, 20, 12 and 36 in the matching runs, and 20 across two instances. The regression test passed all 12 checks on the careful version and failed all 12 on the careless one, with exit code 1.
Where an outside test fits
The worksheet and the table test what you already know about your limits.
A test from outside looks for the endpoints and keys you have not listed. A Clever Ops web application and API penetration test covers authentication and sessions, and a WordPress security audit checks the login and password-reset flows. Lockout and rate-limit checks use a small, agreed number of requests, and Clever Ops does not run load or denial-of-service testing.
Destructive actions are off by default for real people's accounts and records that existed before the test, and reset, lockout and deletion checks run only on test accounts and test records where the rules of engagement allow them.
If Clever Ops built or hosts your application, the work is a security review rather than an independent test, and the report says who built it and who hosts it.
Frequently asked questions
A rule that counts what a client does, such as requests, failed sign-ins or units of work, against a key such as an account or an IP address over a window of time, and refuses or delays the client when the count reaches a limit. It protects accounts from guessing, costly endpoints from running up a bill, and shared capacity from one heavy user. The HTTP status code for the refusal is 429 Too Many Requests, defined in RFC 6585.
RFC 6585 says 429 indicates that the user has sent too many requests in a given amount of time. Its response SHOULD include details explaining the condition and MAY include a Retry-After header. This page's advice is to send Retry-After on every 429, as a whole number of seconds or an HTTP-date, so people and programs know when to come back, and to check that a request sent after that wait succeeds.
Both, plus a device allowance and a global ceiling. An account limit follows the target whichever address the attempts come from, but lets anyone who knows a username use up its allowance. An address limit catches one source trying many accounts, but an office can share one address and an attacker can spread across many. A separate allowance for browsers that have signed in before keeps the owner able to get in while someone else is guessing.
There is no universal number. Set it from your own traffic and write it down: ASVS 5.0 requirement 6.1.1, at Level 1, asks that documentation makes clear how rate limiting is configured and how it prevents malicious account lockout. NIST SP 800-63B-4 section 3.2.2, written for government information systems, says that unless otherwise specified in the description of a given authenticator, the verifier SHALL limit consecutive failed attempts using a specific authenticator on a single account to no more than 100 by disabling that authenticator, and that agencies MAY impose lower limits. Pair the per-account figure with limits per address and device and a global ceiling, and keep a way back in for the customer.
Keep the counters in one shared store, and make each check and count a single step. Redis's INCR page shows a rate limiter that uses MULTI and EXEC so that INCR and EXPIRE both happen on every call. Counters kept in each server's memory let each server allow the full limit: in this page's lab, a limit of 10 became 20 across two instances. Decide in advance what each endpoint does when the store cannot be reached.
Not as of 14 November 2026, when the IETF Datatracker listed them in an active Internet-Draft, draft-ietf-httpapi-ratelimit-headers-11, dated 23 May 2026, with no RFC published. Check the Datatracker for its current state. Retry-After, by contrast, is defined in RFC 9110. If you send the draft fields, the draft says Retry-After takes precedence when a response carries both.
Yes. Whether a limit exists, which key it counts, what it answers and whether customers get back in can each be checked with a few dozen requests against staging, using test accounts and limits lowered so a handful of requests reach them. Load, volumetric and denial-of-service testing is different work, for a load-testing specialist with your host's written approval.
Scope the right test for your application
Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.