How to Configure an Nginx Rate Limit

The two directives

Nginx rate limiting is a leaky-bucket built from a pair:

# http {} - define a zone: key = client IP, rate = allowed average
limit_req_zone $binary_remote_addr zone=api:10m rate=50r/s;

server {
  location /api/ {
    # location {} - apply the zone, with a burst buffer
    limit_req zone=api burst=50 nodelay;
    proxy_pass http://backend;
  }
}

• rate is the steady allowed rate (50r/s, or r/m for per-minute).
• zone=api:10m allocates shared memory to track clients (~160k IPs per 10m).
• $binary_remote_addr keys the limit per client IP.

burst + nodelay (the part everyone gets wrong)

Without a burst, nginx rejects the instant a client exceeds the exact rate - even a normal page that fires a few requests at once gets 503. burst is a queue of extra requests allowed temporarily:

• burst=50 - allow up to 50 queued over-rate requests.
• nodelay - serve those burst requests immediately instead of drip-feeding them.

burst=50 nodelay is the usual "feels normal to users, still capped" setting.

The classic failure: a too-tight limit 503s everyone

A config like rate=1r/m (one request per minute) with no burst will 503 almost all real traffic - the backend looks healthy because nginx is rejecting requests before they reach it. The fix is a realistic rate plus a burst:

limit_req_zone $binary_remote_addr zone=api:10m rate=50r/s;   # was 1r/m
limit_req zone=api burst=50 nodelay;                          # was no burst

Reloading the limit

After changing the rate, a full restart is safer than nginx -s reload - reload keeps the shared-memory zone's in-flight counters, which can keep rejecting requests right after the change. Validate then restart:

nginx -t && nginx -s stop && nginx

Return 429 instead of 503 for rejections with limit_req_status 429; - it's the correct "too many requests" code and clients handle it better.