Skip to content

Rate limiting in Nginx with limit_req — what burst really means

How to use limit_req_zone and limit_req in Nginx to throttle abusive clients, the leaky-bucket model, and the difference between nodelay and delay that catches most operators.

The Nginx limit_req module is the simplest, most effective rate limit you can apply to a public endpoint — protect login pages, API tokens, signup forms, and crawler-friendly paths. The mental model is leaky-bucket: requests dripping in at a sustained rate, with a bucket that holds a short burst. The directives are blunt; what trips operators is the meaning of burst and nodelay.

How to verify

See what limits are active and what they are counting:

sudo nginx -T | grep -E 'limit_req|limit_conn'
sudo grep -E 'limiting requests' /var/log/nginx/error.log | tail
curl -s -o /dev/null -w '%{http_code}\n' -X POST -d 'a=1' https://example.com/login \
  ; for i in 1 2 3 4 5; do curl -s -o /dev/null -w '%{http_code}\n' -X POST -d 'a=1' https://example.com/login; done

If the loop returns a 200 then several 503/429s, your limit is firing. The error log will show limiting requests, excess: 1.000 by zone "login".

What’s happening

A limit_req_zone defines a shared memory zone that counts requests by some key — usually $binary_remote_addr so each client IP is counted separately. The rate is the long-run sustained rate; burst is the bucket capacity for short spikes.

Without nodelay, Nginx queues excess requests up to burst and releases them at the sustained rate — clients see latency rise. With nodelay, Nginx fires them through immediately up to burst, then 503s anything over. delay=N is the middle ground: fire N through immediately, queue the rest.

The unit is requests per second (r/s) or per minute (r/m). 10r/s is one request every 100 ms steady-state.

The procedure

  1. Define the zones in http {} of nginx.conf (or a snippet included from it):
    limit_req_zone $binary_remote_addr zone=general:10m  rate=30r/s;
    limit_req_zone $binary_remote_addr zone=login:10m    rate=5r/m;
    limit_req_zone $binary_remote_addr zone=signup:10m   rate=10r/h;
    limit_req_status 429;
    limit_req_log_level warn;
    10m of zone memory holds ~160 000 unique IPs — adequate for most sites. Use $binary_remote_addr (4 bytes for v4) rather than $remote_addr (string).
  2. Apply per-location:
    location / {
        limit_req zone=general burst=60 nodelay;
        proxy_pass http://app;
    }
    
    location = /login {
        limit_req zone=login burst=5 nodelay;
        limit_req_status 429;
        proxy_pass http://app;
    }
    429 Too Many Requests is the right status here — it tells the client unambiguously what happened. Nginx’s default is 503, which is what you want only if you do not want crawlers to remember the limit.
  3. Decide the key. $binary_remote_addr is fine for v4; for IPv6 the unit-of-rate-limiting question is whether one /64 (one consumer) counts as one or many. For an API behind a CDN where the CDN does not send the original IP, use $http_x_forwarded_for with care — and only if you trust the upstream.
  4. Combine with limit_conn for concurrent-connection limits (different problem — slow clients hogging worker slots):
    limit_conn_zone $binary_remote_addr zone=perip:10m;
    limit_conn perip 20;
  5. Reload and observe error log when you push a real abuse pattern. The limiting requests, excess: lines tell you exactly what fired.
  6. Whitelist trusted sources. Either use a geo block to set a “no limit” variable, or use limit_req_dry_run on; during rollout — Nginx logs what would be blocked without actually blocking.
  7. Bigger throttling story: see Nginx security headers and consider a WAF layer. Nginx rate limiting is a sharp tool for one-IP abuse; it does not defend against distributed credential stuffing.

Common pitfalls

  • rate=10r/m with burst=100 — burst is in requests, not “requests per minute”. A client can fire 100 immediately, then is throttled to 1 every 6 seconds. Newcomers expect 100/minute instead.
  • nodelay without burst — no burst means strict sustained rate, latency goes up immediately, and you have probably built a self-inflicted DOS on a real-user traffic spike.
  • Limit zone keyed on $remote_addr behind a load balancer that shows up as a single IP — your entire site is now rate-limited to whatever the per-IP rate is.
  • Sharing one zone across many limits — the counters collide. Each named zone counts independently.
  • Memory sized too small. A “zone exhausted” condition silently stops counting — Nginx logs it once per minute.

In the engagements we run, the rate-limit block is one of the boring-but-load-bearing pieces of every production Nginx config. We template it per environment and connect the error log lines into the alerting pipeline so an abuse pattern shows up in managed operations before the customer notices.