Nginx limit_req Rate-Limit Lab: Burst, nodelay, and the return Pitfall

Intro — what this post promises

Rate limiting is the cheapest “please stop hitting me” lever on a reverse proxy. Nginx’s limit_req is also one of the easiest knobs to misconfigure: the docs look short, the zone looks fine, and every request still returns 200.

This post is a localhost lab with measured numbers:

1. What limit_req_zone + limit_req actually do (leaky bucket, not a hard RPS ceiling you can eyeball).
2. A baseline flood with no limit.
3. The same flood with rate=5r/s burst=10 nodelay and with no burst.
4. Paced clients at under / at / over the configured rate.
5. The pitfall that made our first configs look “broken”: return in the same location bypasses limit_req.
6. How this ties to latency graphs and a first observability stack — without repeating those posts.

Related links:

• Why your average latency graph is lying (p50 / p95 / p99)
• OpenTelemetry Collector + Prometheus + Grafana first stack
• How to read server monitoring graphs

Lab honesty (30 Sep 2026 IST): Shared Linux lab box (8 cores). nginx/1.26.3 as a host binary (Debian package). Four separate nginx masters, each bound to 127.0.0.1 only on ports 18080–18083. No Docker. No public bind. Static try_files → index.html (“ok”). Client floods: Python urllib thread pool + paced sequential loops. Affiliates: 0.

Verdict up front: limit_req works and is worth running on login, search, and other abuse-prone paths — but only after you confirm 429s under a real burst, not after a green config test.

What limit_req is (and is not)

Nginx documents limit_req_zone as a shared-memory zone keyed by a variable (usually $binary_remote_addr) with a rate, and limit_req as the per-location application of that zone with an optional burst and nodelay.

Related links:

• Module ngx_http_limit_req_module

Mental model that matched our lab:

This is not a global “API quota” product. It is per-key (here: one IP). Behind a CDN you need real-IP / trusted proxy setup or you rate-limit the CDN edge, not the client.

Lab topology

Python flood / paced client
        |
        |  HTTP GET /
        v
[nginx 1.26.3] 127.0.0.1:18080  baseline (no limit_req)
[nginx 1.26.3] 127.0.0.1:18081  rate=5r/s burst=10 nodelay
[nginx 1.26.3] 127.0.0.1:18082  rate=5r/s (no burst)
[nginx 1.26.3] 127.0.0.1:18083  rate=1r/m burst=1 nodelay (sanity)

Minimal limited location (shape we ended on):

limit_req_zone $binary_remote_addr zone=perip:10m rate=5r/s;
limit_req_status 429;

server {
  listen 127.0.0.1:18081;
  root /path/to/html;
  location / {
    limit_req zone=perip burst=10 nodelay;
    try_files /index.html =404;
  }
}

We deliberately did not put return 200 "ok\n"; in that location. See the pitfall section.

Results (measured)

Instant flood — 200 requests, 50 workers

The 11 successes with burst=10 match the expected “about one in-rate token + 10 burst” story for an instantaneous dump against an empty bucket. The 1 success with no burst matches “empty bucket allows the first request, rejects the rest.”

Repeat flood on the limited port (100 requests / 40 workers after refill sleep): again 11×200 and 89×429. Same shape, not a fluke.

Error log (warn level) on rejects looked like:

limiting requests, excess: 10.950 by zone "perip", client: 127.0.0.1, ...

Paced clients on the limited port (5r/s burst=10 nodelay)

At the configured rate, the leaky bucket keeps up. Well under the rate, everything is green. At 20 r/s, burst absorbs some of the early excess, then half the sample is rejected — which is exactly the “burst is not infinite headroom” lesson.

Sanity: 1r/m burst=1 nodelay sequential

10 quick sequential GETs: 2×200, then 8×429. Confirms rejecting works even without a thread pool.

Pitfall: return bypasses limit_req

Our first configs used:

location / {
  limit_req zone=perip burst=10 nodelay;
  return 200 "ok\n";
}

Config test passed. Floods returned 200/200. Error log stayed quiet. It looked like limit_req was broken.

Nginx phase order is the reason: return is handled in the rewrite phase; limit_req runs in preaccess. Rewrite finishes first, so the request never reaches the limiter.

Fix that worked in this lab: serve a static file with root + try_files (content phase), or proxy_pass an upstream. Then the same limit_req line produced the 429 tables above.

If your “rate limit” never fires in staging, check for return / early rewrite exits in the same location before you tune burst.

What we would put in front of a real API next

1. Bind carefully — this lab used 127.0.0.1 only. Production listens where the load balancer expects, with TLS at the edge.
2. Pick the key — IP is the default; authenticated routes often want a user id (and a separate, stricter zone for anonymous).
3. Status code — set limit_req_status 429 so clients and scrapers see Too Many Requests, not a fake upstream failure (503).
4. Observe rejects — count 429s and limiting requests warnings next to golden signals. Rate-limit mistunes show up as traffic and error-rate symptoms, not as “CPU is fine.”
5. Do not confuse with latency SLOs — a healthy limited path still needs p95/p99 on the 200 path; rejecting junk should not be your only latency strategy.

Related links:

• Why your average latency graph is lying
• OTel + Prometheus + Grafana first stack
• How to read server monitoring graphs

FAQ

Why 429 instead of 503?

Nginx defaults limit_req rejects to 503. We set limit_req_status 429 so the client semantics match “slow down,” not “server broken.” Either works operationally; be consistent with what your clients and alerts expect.

Does burst=10 mean 10 r/s?

No. rate is the sustained refill. burst is short-term excess capacity. In our instant flood, burst=10 meant about 11 successes, not 10 r/s forever.

What about limit_conn?

Different tool: connection concurrency, not request rate. Useful for slowloris-style pressure; not a substitute for limit_req on chatty HTTP/1.1 or HTTP/2 request storms.

Will this stop distributed scrapers?

Per-IP limits stop noisy single sources. Distributed scrapers need edge/WAF/bot management and application auth. limit_req is still useful as a cheap inner fuse.

Can I lab this without Docker?

Yes. This entire post ran on a host nginx binary and localhost ports.

Verdict

Ship limit_req on abuse-prone locations after a burst test that proves 429s. Our numbers: baseline flood 200/200 OK; with 5r/s burst=10 nodelay, the same flood dropped to 11 OK and 189×429; with no burst, 1 OK and 199×429; paced traffic at 5 r/s stayed 100% OK. The config that “passes nginx -t” is not enough — especially if return short-circuits the limiter.

Affiliates: 0. No product hop. Evidence lives under the lab tree used for this write-up (lab-evidence/11-nginx-rate-limit/).

Related ShopperCove posts

• Why your average latency graph is lying (p50 / p95 / p99)
• OpenTelemetry Collector + Prometheus + Grafana
• How to read server monitoring graphs