Skip to content
Tutorials Center
My learning

Topics

Lesson 80 of 133 ยท Security and Cryptography

Rate Limiting and API Protection

Protect a Node.js API with a token bucket rate limiter, per-client limits, 429 and Retry-After responses, CORS rules and security headers, all built with plain node:http.

A public API is a shared resource. One buggy client stuck in a retry loop, one scraper, or one attacker guessing passwords can use up the CPU, the database connections and the bandwidth that everyone else needs. Rate limiting is the defense: you decide how many requests a client may make in a period, and you answer the rest with a clear "slow down" instead of doing the work.

Limiting is only one layer. A well-protected API also decides which web pages may call it from a browser (CORS), tells browsers to behave safely with its responses (security headers), and bounds the size and time of every request. In this lesson you build all of these with nothing but node:http, so you can see exactly what frameworks and middleware do for you. The ideas connect to Web Security Essentials, Middleware Patterns and Designing REST APIs.

Why limit, and what to limit

Rate limiting protects you from three different things:

  • Accidents. A client with a bug in a loop can send thousands of requests per second.
  • Abuse. Scrapers, credential stuffing (trying many passwords) and enumeration of IDs.
  • Cost. Expensive endpoints (search, report generation, anything that calls a paid service) need tighter limits than cheap ones.

You pick a key that identifies "who" is being limited, and a budget for that key. Common keys are the client IP address, an API key, a user ID, or a combination such as IP plus route. Use different budgets per route: a login endpoint might allow 5 attempts per minute, while a read-only list endpoint allows 100.

A limiter that lives in your process memory only counts requests that reach that process. If you run several copies behind a load balancer, each copy has its own counters, so a client can get several times the budget. Production setups move the counters to a shared store such as Redis, or enforce the limit at the edge (reverse proxy or CDN). The algorithm stays the same.

The token bucket algorithm

The most popular limiter is the token bucket. Picture a bucket that holds at most capacity tokens. Every request must take one token out. Tokens are added back at a steady refillPerSecond rate, but the bucket never holds more than its capacity. If the bucket is empty, the request is rejected.

flowchart LR
  R["Refill: N tokens per second"] --> B(("Bucket<br/>max = capacity"))
  Q["Incoming request"] --> C{"Token<br/>available?"}
  B --- C
  C -->|yes| T["Take 1 token<br/>handle request"]
  C -->|no| X["Reject with 429"]

A token bucket: a steady refill, a hard cap, and one token spent per request.

Two numbers describe the behavior. The refill rate is the sustained speed a client may keep up forever. The capacity is the burst it may do after being quiet: a bucket of 5 with a refill of 1 per second allows 5 requests instantly, then one per second afterwards. That matches real traffic well, because people click in bursts.

You do not need a timer to refill the bucket. Store the number of tokens and the time of the last update; when a request arrives, compute how much time passed, add elapsed * rate tokens (capped), and then try to take one. That is "lazy refill", and it costs nothing for idle clients.

To make the code testable, the limiter below receives the clock as a function. In production you pass () => performance.now(); in the demo we pass a fake clock that we move by hand, so the output is always the same.

Node.js A token bucket with a fake clock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that the first three requests pass at once (the burst), the next two are rejected with a retryAfter hint, and after a long pause the bucket is full again but never holds more than three tokens.

Other algorithms exist. A fixed window counter ("100 requests per minute, reset on the minute") is simplest, but allows a double burst around the boundary: 100 requests at 12:00:59 and 100 more at 12:01:00. A sliding window fixes that at the cost of more memory. The token bucket is a good default because it needs only two numbers per client.

Limiting per client in a server

Now put the bucket in front of an HTTP handler. We keep one bucket per key in a Map, and we answer with the standard pieces:

  • Status 429 Too Many Requests when the budget is spent.
  • A Retry-After header with the number of seconds to wait.
  • Informational headers such as RateLimit-Remaining so well-behaved clients can slow down before they are rejected. (The exact names are still being standardized; many APIs use X-RateLimit-* or RateLimit-*. Pick one family and document it.)

Two details matter in practice.

Who is the client? req.socket.remoteAddress is the address of the TCP peer. Behind a reverse proxy or CDN that is the proxy's address, so every user would share one bucket. Proxies pass the real address in X-Forwarded-For, but anyone can send that header themselves. Only trust it when your own proxy sets it, and read the entry that your proxy added (the right-most one you trust), never blindly the first value.

Memory. A Map with one bucket per IP grows forever. Delete buckets that have been idle long enough to be full again, for example in an interval that you unref() so it does not keep the process alive.

In the demo, the key comes from a made-up header x-demo-client so that one machine can pretend to be several clients. The code that builds the key is a function you would replace with your real choice.

Node.js A per-client limiter in an HTTP server

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Alice is limited, but Bob is not: each key has its own bucket. That separation is the whole point of "per-client".

A few extra rules make a limiter robust:

  • Count failures separately for sensitive routes. For login, count attempts per account name and per IP, because an attacker can rotate IPs while attacking one account, or use one IP against many accounts.
  • Limit concurrency too. A cap on requests in flight protects slow endpoints that a low request rate would not.
  • Reject early and cheaply. Run the limiter before parsing bodies, hitting the database or doing any heavy work.
  • Don't reveal too much. A 429 should say that the limit was hit and when to retry, not how your internals work.
  • Tell clients how to behave. Good clients wait for Retry-After, then retry with exponential backoff and jitter.

Bounding every request

Rate limits count requests; you must also bound what a single request can cost. Node's http server has settings for this, and you should know the main ones (see The http Module: Servers):

Setting Protects against
server.headersTimeout Clients that send headers extremely slowly (slowloris)
server.requestTimeout A request that never finishes arriving
server.maxHeadersCount and --max-http-header-size Huge header blocks
A body size limit you enforce while reading Gigabyte uploads to a JSON endpoint

For bodies, count bytes as the chunks arrive and stop reading the moment the total passes your limit, replying 413 Content Too Large. Never buffer first and check after. Request Bodies, JSON and Forms shows the pattern.

CORS: which web pages may call your API

Browsers apply the same-origin policy: a script on https://shop.example cannot read responses from https://api.example unless the API opts in. The opt-in is called CORS (cross-origin resource sharing), and it is done with response headers.

Important facts that save hours of confusion:

  • CORS is enforced by browsers, to protect users. It does not stop curl, scripts or other servers from calling your API, so it is not authentication and it is not a replacement for rate limiting.
  • For "simple" requests the browser sends the request and then checks Access-Control-Allow-Origin on the response. For anything else (a PUT/DELETE, a JSON Content-Type, an Authorization header) it first sends a preflight, an OPTIONS request, and only continues if the answer allows it.
  • Answer a preflight with 204 and Access-Control-Allow-Methods, Access-Control-Allow-Headers and optionally Access-Control-Max-Age to let the browser cache the decision.
  • Use an allow list of origins and echo back the matching one. Add Vary: Origin so caches do not serve one origin's answer to another. Avoid * for APIs that use cookies; browsers refuse * together with credentials anyway.
sequenceDiagram
  participant B as Browser (shop.example)
  participant A as API (api.example)
  B->>A: OPTIONS /orders (Origin, Access-Control-Request-Method: DELETE)
  A-->>B: 204 + Allow-Origin, Allow-Methods, Allow-Headers
  B->>A: DELETE /orders/7 (Origin)
  A-->>B: 200 + Allow-Origin
  Note over B: The page may now read the response

A preflighted cross-origin request: the browser asks permission first, then sends the real request.

Security headers

Some response headers tell the browser to turn on protections. They cost nothing and close whole classes of attacks. A sensible starting set for an API:

Header Value What it does
X-Content-Type-Options nosniff Stops the browser from guessing a different content type
Cache-Control no-store (for private data) Keeps sensitive responses out of shared caches
Content-Security-Policy default-src 'none'; frame-ancestors 'none' A JSON API has nothing to load or to be framed by
Strict-Transport-Security max-age=31536000; includeSubDomains Tells browsers to use HTTPS only (send it over HTTPS)
Referrer-Policy no-referrer Avoids leaking URLs to other sites
Cross-Origin-Resource-Policy same-site or cross-origin Controls who can embed the response

Also remove information you do not need to share, such as framework banners (Express users call app.disable('x-powered-by'); plain node:http does not add one).

The example below combines everything into one small, reusable wrapper: security headers on every response, CORS with an allow list, preflight handling and a body size limit. The client plays the roles of an allowed page, a stranger and a browser preflight.

Node.js CORS allow list, preflight and security headers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at the "unknown origin" result: the request still succeeds with 200, but there is no Access-Control-Allow-Origin header, so a browser would refuse to hand the response to the page. That is why you also need authentication and rate limiting: CORS alone only controls browsers.

Putting the layers in order

The order of checks matters, because each layer should be cheap compared with the next. A good pipeline for each request is:

  1. Security and CORS headers, and answer preflights (no work at all).
  2. Rate limit by IP (cheap lookup in memory).
  3. Authenticate, then rate limit by user or API key.
  4. Read the body with a size limit and a timeout.
  5. Validate the input.
  6. Do the real work.

Finally, log rejected requests (see Logging) so you can see abuse patterns, and alert when the number of 429 responses jumps.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A token bucket has capacity 5 and refills 1 token per second. A client was idle for a minute. How many requests can it send instantly?

    Idle time refills the bucket, but never beyond its capacity of 5, so the burst is at most 5. After that the client is limited to 1 per second.
  2. 2. Which response tells a client how long to wait after being rate limited?

    429 Too Many Requests is the standard status, and Retry-After gives the number of seconds (or a date) the client should wait before retrying.
  3. 3. Why is it dangerous to trust the first value of X-Forwarded-For from any request?

    Only a proxy you control can be trusted to set it. If you trust a client-supplied value, a limiter keyed on it is trivial to bypass.
  4. 4. Does CORS stop a script on a server from calling your API?

    CORS protects users inside browsers. curl, server-side code and other tools ignore it, so you still need authentication, validation and rate limiting.
  5. 5. Where should the body size limit be enforced?

    Checking after buffering already costs the memory you wanted to protect. Count bytes per chunk and stop reading with a 413 once the limit is passed.

Summary

  • Rate limiting protects shared capacity from accidents, abuse and cost; choose a key (IP, API key, user) and a budget per route.
  • A token bucket allows a sustained rate plus a burst, and refills lazily from the elapsed time, so idle clients cost nothing.
  • Answer rejected requests with 429 and Retry-After; expose remaining budget in headers; clear idle buckets; move counters to Redis or the edge when you run several instances.
  • Never trust X-Forwarded-For unless your own proxy sets it.
  • Bound each request: header and request timeouts, and a body size limit enforced while reading (413).
  • CORS is a browser-only opt-in controlled by response headers; use an allow list, handle preflights and add Vary: Origin.
  • Send security headers (nosniff, a restrictive CSP, HSTS over HTTPS, no-store for private data) on every response.

Next: Compression with zlib