When to rate-limit — and what you are actually capping

An endpoint without a cap is an invoice you did not sign. Login hashes. Search reads. Webhooks write. A model costs per token. A scraper, a stuffed login, a 'try every company number' script, a webhook you called in a loop — same class: someone found the expensive thing, and you pay until you say no. The cap is not paranoia. It is refusing to subsidise the work you would not run by hand.

Teams inherit the words rate limiting from another layer. In an edge incident it is 'block the country'. In an API gateway it is tokens per key. In a Next.js route it is often a middleware someone copied, that counts wrong, shows 500, and hits the wrong path. You think you have protected the API. You have moved the pain onto the homepage, or you have a cap that resets every time an instance starts. The ritual is expensive because it gives you permission not to point at the call that actually hurts.

It is also a trust and product question. A 429 without Retry-After is a failure the user blames on you. A 403 on a login that was only too fast is a lockout you cannot explain. A captcha in front of the whole site, because you would not own a cap on `/api/search`, is theatre: you punish the reader for not limiting the scraper. If nobody owns the 429 page, the cap is a network signal. It is not a product.

We write this because 'we must protect the API' has become a purchase you make before you have a sentence about which call, which identity and which 429. An honest setup is boring: caps on login, search, webhooks and whatever calls onward; a shared counter; honest status. Without that sentence you have a WAF rule with a number. You do not have rate limiting.

Rate limiting is a cap on a named call in a named window: this many login attempts per account and per IP per quarter-hour, this many searches per session per minute, this many webhook retries per source. It is a product choice, because it says who you think you are and what you accept to run. It is not an insult. Most public sites should have it on three paths, not on every path.

It is not 'block bots'. A WAF, a managed challenge, a bot score, is a different job: keep the crude stuff out before it hits origin. That is right, and it is not the cap. The cap is what happens when the call is already yours — a real user, a real key, a real form — and you still say no because it is too often. If you only have a WAF, you have a hope that the expensive call will not come in. You have not said no to what came in.

It is also not 'put a number on the hostname'. A global request limit hits the page you want crawled, and lets `/api/login` be what survives because it is fewer bytes. The attacker chooses the expensive thing. You limit the cheap thing. An honest cap starts with the sentence 'this call costs us in CPU, in vendor, in lockout risk' — qualitative, not dashboard theatre. Without that sentence the number is interior design.

And it is not an in-memory Map in a serverless function. Three instances, three counters, three times the cap. A deploy, and the counter is gone. Rate limiting that does not survive a new instance is a suggestion. Use something shared: KV, Redis, a platform rate limit, edge cache with a key. Pick the boring thing that counts correctly. A clever number on three holes is still three holes.

The first failure is limiting the visible, not the expensive. You cap `/` because that is what you can see in the CDN log, and let `/api/search`, `/api/auth` and the webhook route run. You have moved the graph. You have not moved the risk. An honest cap starts with the call you would not run in a loop by hand. If you cannot point at it, you are not ready for a number. You are ready to read your own routes.

The second failure is the counter you did not share. Next.js on Vercel, Cloudflare Workers, two regions, preview and prod. A Map in the module, a cookie you set yourself, an edge middleware without storage. It works in one window. It does not work when three isolates take the next three requests. You get a cap you can demo, and a hole you pay for. Shared state is the duty. Anything else is a local cap you call global.

The third failure is the status code and the body. A 500 on too many logins is a lie: you know exactly what happened. A 200 with `{ ok: false }` is a hole the client cannot tell from validation. A 403, as if the user were banned, is a lockout you cannot explain to support. 429 is the word. Retry-After is the time. The UI should say 'try again in a moment', not 'something went wrong'. The error-pages post is the screen. Here the duty is to let the cap be true in the header.

The fourth failure is buying identity theatre before you have a cap. 'We will wait for SSO, then we will limit.' Meanwhile public search and the public form are open. You can limit on IP and on cookie until you have a user. That is crude. It is better than nothing. A NAT is a problem you can absorb with a higher cap and a second signal. No identity is not a reason to let `/api/login` run unbounded.

Login and password reset are the cap that is most often right because of lockout risk, not CPU. You do not want to hash a flood of guesses. You do not want to send a flood of reset mail. Identity beats IP when you have an account. IP beats nothing when you do not. An honest login cap is tight per account, coarser per IP, and a 429 that does not sound like 'wrong password'. Mix the two and you have given an attacker an oracle. The security post is headers and secrets. Here the duty is to make the guess expensive for them, not for you.

Search and typeahead are the cap that is most often right because of the origin bill. Every keystroke is a database call unless you cache. A scraper that loves your `/api/search` is not a reader. A global hostname cap hits the blog. A cap on the search route hits the job. Cache what you can. Limit what you cannot. If you 'protect the API' by requiring login to search a public catalogue, you have moved the product. You have not moved the cap.

Webhooks in and out are the cap you forget until a partner retries in a loop, or until your own job calls you. Sign the secret. Idempotency on event id. And a cap per source, so a failing handler does not become a denial you paid for. That is not 'protect the API'. That is refusing to let a loop you own look like traffic. The observability post is seeing it. Here it is saying no once you have seen it enough.

The public form — contact, 'book a conversation', newsletter — is the cap that most often becomes captcha theatre. Captcha can be right when you have a human in front of an expensive action. It is wrong as a substitute for a cap: you can limit per IP and per field-hash, hide a honeypot, and still show the form. The cookie-banner post is consent. This one is making spam expensive without punishing the person who writes three honest lines. A portal landing is what you build when the form has become a workflow — not when you just needed to say 429.