What is limit_req and how does limit_req_zone track requests?
Nginx rate limiting uses two directives. limit_req_zone defines the policy: what to count, where to store the counts, and how fast requests may arrive. limit_req applies that policy to a server or location block. Keeping them separate lets one zone protect several routes, or lets different routes such as login, search and bulk export each get their own budget. That makes the pair useful for API abuse protection and for keeping expensive endpoints from overwhelming upstream services.
limit_req_zone takes three parts:
- Key. The value requests are grouped by, usually the client address. Prefer
$binary_remote_addrover$remote_addr. The binary form is a fixed 4 bytes for IPv4 and 16 bytes for IPv6. The text form is a variable-length string of up to 15 characters for IPv4 and more for IPv6. A smaller key means each tracked client uses less memory, so the same zone holds more clients. - Shared memory zone. For example,
zone=api:10mcreates a named area that all worker processes read and write, so the limit applies across the whole instance rather than per worker. Size it for the number of distinct keys you expect. When the zone fills, Nginx evicts the least recently used entries, and if it still cannot store a new key, it rejects that request. - Rate. Expressed as
r/sorr/m. User/mfor anything slower than one per second, such as30r/mon a login route.
Nginx tracks rates at millisecond granularity. 10r/s means one request every 100 ms, not a batch of ten allowed at the start of each second. A client that sends two requests 20 ms apart has exceeded the rate even though it is far below ten per second. That second request is rejected unless you configure burst, which the following sections cover.
http {
# Zone 'api': key by client IP in binary form (4 bytes IPv4, 16 bytes IPv6),
# 10 MB of shared memory visible to all workers, 10 requests per second.
# Nginx enforces this as one request every 100 ms, not 10 per clock second.
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
# Separate, slower budget for login: 30 per minute = one every 2 seconds.
limit_req_zone $binary_remote_addr zone=login:10m rate=30r/m;
upstream app_backend {
server 127.0.0.1:8080;
}
server {
listen 80;
server_name api.example.com;
# General API routes share the 'api' zone.
location /api/ {
limit_req zone=api;
proxy_pass
}
# Login gets its own stricter policy to slow credential stuffing.
location = /login {
limit_req zone=login;
proxy_pass
}
# No burst is configured yet, so a second request arriving sooner than
# the interval (e.g. 20 ms after the first on /api/) is rejected.
}
}
Two limit_req_zone policies keyed on $binary_remote_addr, one at 10r/s for API routes and one at 30r/m for login, each applied to its own location with limit_req and no burst configured yet.
Who should use limit_req?
limit_req fits teams that already run Nginx in front of their services and want a cheap, local guard against request floods. Typical users include:
- API owners behind an Nginx reverse proxy or ingress. They need to stop a single misbehaving client, script or retry loop from saturating the backend.
- Teams protecting sensitive or expensive endpoints. Login, password reset, search and export routes benefit from their own slower zones, which slow credential stuffing and keep heavy queries from piling up.
- Small teams without a dedicated API gateway. The module is part of standard Nginx builds and needs only configuration, so it adds protection without adding a new service to operate.
- Platform teams that maintain shared Nginx baselines. A reviewed include with sensible zones, key handling and exemptions gives every service the same starting protection.
It is the wrong primary tool if you need exact per-customer quotas, limits enforced consistently across a fleet, or billing-grade counts. The "When should you avoid relying on Nginx rate limiting?" section covers those cases in detail.
How does limit_req work, step by step?
For each request that reaches a location with limit_req, Nginx runs the same sequence. The module acts in the preaccess phase, which comes before access checks and before the request is proxied, so rejected requests never consume upstream capacity.
- Compute the key. Nginx evaluates the key expression from
limit_req_zone, such as$binary_remote_addr. If the result is empty, the request is not counted against that zone. - Look up state in shared memory. Nginx finds the key's entry in the zone, or creates one. The entry records the key's current excess and the time of the last accepted request. Because the zone lives in shared memory, all worker processes on that instance see the same state.
- Drain the bucket. Nginx reduces the stored excess by the amount the configured rate would have drained since the last accepted request. At
10r/s, 100 ms of elapsed time drains one request's worth. - Add the new request and compare. The new request adds one to the excess. If the result exceeds
burst, the request is rejected withlimit_req_statusand logged atlimit_req_log_level. - Pass or delay. If the excess is within
burst, the request is accepted. Withnodelay, or when the excess is within thedelaythreshold, it is forwarded immediately. Otherwise Nginx holds it on a timer until the drain reaches it, then forwards it. The worker is not blocked while it waits and keeps serving other connections. - Combine multiple limits. If a context has several
limit_reqdirectives, each zone is checked. Any one of them can reject or delay the request, which is why the most restrictive limit decides the outcome.
The following sections explain the bucket model behind steps 3 to 5 and how burst, nodelay and delay change the result.
How does the leaky-bucket model decide which requests are rejected?
The leaky-bucket model is the clearest way to reason about what burst changes. Picture a bucket that drains at exactly the configured rate. With rate=10r/s, Nginx drains one request every 100 ms. Every arriving request tries to go into the bucket. If there is room, it is accepted, either forwarded now or held until the drain reaches it. If there is no room, it is rejected with a 503 by default, or with whatever status you set in limit_req_status.
rate=10r/s, burst=3 (drain: 1 req / 100 ms)
arrivals t=0ms: R1 R2 R3 R4 R5
| | | | |
v v v v v
bucket [R1 forwarded][R2][R3][R4] R5 -> rejected (no room)
|
drain R2 @100ms, R3 @200ms, R4 @300ms
The bucket's size sets how many excess requests can be absorbed at once. It has no effect on the long-run throughput. Over any sustained period, a client still gets roughly ten requests per second. burst, nodelay and delay decide what happens to requests above that line: whether they wait in the queue, are forwarded immediately while still occupying a slot, or are dropped.
Without burst, the bucket has no spare room. Nginx tracks the excess with millisecond granularity, so any request that arrives less than 100 ms after the last accepted one is rejected. This is why a bare limit_req zone=api; misbehaves in practice. A browser loading a page fires several requests at once. An HTTP/2 client multiplexes parallel calls over one connection. A mobile app often fetches several resources on launch. These clients stay well under ten requests per second on average, but they arrive in clusters, and every request after the first in each cluster fails.
http {
# One shared-memory zone keyed by client IP: 10 requests/second,
# which Nginx enforces as one request per 100 ms.
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
# Return 429 instead of the default 503 for rejected requests.
limit_req_status 429;
server {
listen 80;
# Strict: no burst. A second request arriving within 100 ms of the
# last accepted one is rejected, so a page that fires 5 parallel
# requests gets 1 success and 4 rejections.
location /strict/ {
limit_req zone=api;
proxy_pass
}
# Queued: up to 3 excess requests wait in the bucket and are
# released at the drain rate (100 ms, 200 ms, 300 ms). The 5th
# request in a simultaneous cluster is rejected.
location /queued/ {
limit_req zone=api burst=3;
proxy_pass
}
# Immediate: the same 3 excess slots, but requests are forwarded
# without waiting. Each slot still frees up only at the drain
# rate, so long-run throughput stays at about 10 r/s.
location /immediate/ {
limit_req zone=api burst=3 nodelay;
proxy_pass
}
}
}
Three locations share one 10r/s zone and differ only in how they treat excess requests: rejecting any request that arrives too soon, queuing a few at the drain rate, or forwarding them immediately while they hold a bucket slot.
What do burst, nodelay and delay actually do?
burst is a queue size, not a second rate. With rate=10r/s burst=20, Nginx admits one request per 100 ms and lets up to 20 excess requests wait in line. Anything beyond that is rejected with 503 by default.
Illustrative estimate. Assume one client sends 25 requests at once:
- Default (burst only): 1 is served immediately and 20 are queued, then released about every 100 ms. The last queued request waits about 2 s. The remaining 4 are rejected.
- With
nodelay: 21 are forwarded immediately and 4 are rejected. The 20 queue slots stay occupied and free up at only one per 100 ms. If the client sends a second burst 300 ms later, roughly 3 requests get through and the rest are rejected.nodelayremoves the waiting, but it does not raise the long-term rate. - With
delay=8: This is two-stage limiting. The first 9 requests pass immediately, which covers the parallel calls a page load or app launch makes. The next 12 are paced, and the last of them waits about 1.2 s. The final 4 are rejected.
| Mode | Immediate | Delayed | Rejected | Max added latency | Upstream concurrency |
|---|---|---|---|---|---|
burst=20 |
1 | 20 | 4 | ~2 s | ~1, paced |
burst=20 nodelay |
21 | 0 | 4 | none | up to 21 at once |
burst=20 delay=8 |
9 | 12 | 4 | ~1.2 s | up to 9, then paced |
Each mode has a cost:
- Queued requests hold client connections open the whole time they wait. Clients with short timeouts may give up and retry, which adds load at the worst moment.
nodelaysends the full burst upstream at once. Setburstto what the backend can absorb concurrently, not to what feels generous.
http {
# One shared zone keyed by client IP: 10 MB of state, 10 requests/second.
# The rate is the long-term drain rate. burst/nodelay/delay never raise it.
limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;
upstream app_backend {
server 10.0.0.10:8080; # placeholder backend
}
server {
listen 80;
# Mode 1: burst only. Up to 20 excess requests wait in a queue and are
# released about every 100 ms. Upstream sees a paced stream. Clients
# may wait up to ~2 s, so their timeouts must tolerate that.
location /reports/ {
limit_req zone=perip burst=20;
proxy_pass
}
# Mode 2: nodelay. Up to 21 requests are forwarded at once and the queue
# slots refill at 10r/s. Only use this if the backend can absorb ~21
# concurrent requests from a single client.
location /api/ {
limit_req zone=perip burst=20 nodelay;
proxy_pass
}
# Mode 3: two-stage limiting. The first 9 requests pass immediately,
# which covers a page load's parallel fetches. The next 12 are paced
# and anything beyond burst is rejected. delay and nodelay are
# mutually exclusive.
location / {
limit_req zone=perip burst=20 delay=8;
proxy_pass
}
}
}
This config shows the three limit_req modes from the table (burst only, burst with nodelay, and burst with delay=8) applied to separate locations that share one 10r/s per-client zone.
How do you implement limit_req for an API in production?
Start with the response itself. Set limit_req_status 429 so clients see "Too Many Requests" instead of the default 503, which looks like an outage and can trigger the wrong alerts and retry logic. Set limit_req_log_level warn to separate rejections from real errors. Nginx then logs delayed requests one level lower. Recent releases also offer limit_req_dry_run, which counts and logs excess requests without rejecting them. Check your version's documentation before you depend on it.
Choosing the key
Behind a load balancer or CDN, $binary_remote_addr is the proxy's address, so every client shares one bucket. Use the real_ip module: set set_real_ip_from to the proxy ranges you trust, set real_ip_header to the forwarding header, and enable real_ip_recursive. Never trust the forwarding header from arbitrary sources, because clients can forge it. For per-tenant limits, key on an API key or a value derived from the auth header.
Nginx does not count requests with an empty key. You can use that for exemptions: a map that returns "" for health checks or internal ranges, and the real key for everything else.
Layering zones
You can put several limit_req lines in one context, such as one per IP and one per API key. Nginx applies all of them, and the most restrictive one decides the outcome. A limit_req in a location replaces the directives inherited from server or http rather than adding to them. If you add one there, repeat any limits you want to keep.
Write this setup once as a reviewed baseline include. Each service can then reuse correct key handling and exemptions instead of rediscovering these pitfalls on its own.
set_real_ip_from 10.0.0.0/8; # trusted LB range (placeholder)
set_real_ip_from 192.0.2.0/24; # trusted CDN range (placeholder)
real_ip_header X-Forwarded-For;
real_ip_recursive on; # skip trusted hops, use first untrusted address
geo $rl_exempt {
default 0;
10.20.0.0/16 1; # internal monitoring/health checks (placeholder)
}
map $rl_exempt $rl_ip_key {
0 $binary_remote_addr;
1 "";
}
map $rl_exempt $rl_tenant_key {
0 $http_x_api_key; # also empty if the client sends no key
1 "";
}
limit_req_zone $rl_ip_key zone=per_ip:10m rate=10r/s;
limit_req_zone $rl_tenant_key zone=per_tenant:10m rate=50r/s;
limit_req_status 429; # not the default 503
limit_req_log_level warn; # delayed requests are logged one level lower
server {
listen 80;
location /api/ {
# Both limits apply, and the most restrictive one wins. A limit_req here
# replaces any inherited from server/http, so list every limit you need.
limit_req zone=per_ip burst=20 nodelay;
limit_req zone=per_tenant burst=100 nodelay;
proxy_pass
}
}
This baseline sets the real client IP from trusted proxies, exempts internal ranges through empty map keys, returns 429, and layers per-IP and per-API-key zones in a single location.
How do you test limit_req before rolling it out?
Fire more requests than the limit allows from a single client and watch both the outcome and the timing of each one. A parallel curl loop (for example, curl driven by xargs -P) is enough to probe burst edges. A load tool such as ab or wrk is better for sustained rates. Record each request's status code and total time, because the two together reveal which path Nginx took:
- Fast success: the request was admitted immediately, either within the rate or as a
nodelayburst slot. - Slow success: the request was queued in the burst and released at the configured rate. On a
10r/szone, queued requests finish roughly 100 ms apart. - Fast rejection: the bucket overflowed. The response carries 503 by default, or whatever
limit_req_statussets, commonly 429.
If you only count status codes, you will miss delays, and those delays can push upstream clients past their own timeouts.
Make sure your test traffic produces the same key that production traffic will. If staging sits behind a different proxy chain, every request may collapse onto one address, or each may get its own. Either way, the results tell you little about production.
Check the error log alongside the client output. Rejections are logged as "limiting requests" with the excess value and zone name. Delays are logged as "delaying request" one level below limit_req_log_level. Adding $limit_req_status to the access log format labels every request as passed, delayed or rejected. That makes it easy to correlate with your client-side numbers.
For the first production rollout, enable limit_req_dry_run. Nginx then evaluates and logs every decision but never delays or rejects a request. A few days of those logs show which real clients would have been throttled. You can tune the rate, burst and key before any legitimate traffic is turned away.
How can limit_req save engineering time?
Most of the time savings come from enforcing limits in configuration you already run, instead of building and maintaining them in each service.
- No application code changes. Adding a zone and a
limit_reqline protects an endpoint without touching the service behind it. Teams do not have to write, test and deploy rate-limiting logic in every codebase and language they use. - Fewer abuse-driven incidents. Runaway scripts, broken retry loops and crude floods are rejected in the preaccess phase, before they reach the upstream. Engineers spend less time diagnosing overloaded backends and databases that were caused by a single client.
- One reviewed baseline instead of many implementations. A shared include with the real_ip setup, exemptions,
limit_req_status 429and log level settings captures the pitfalls once. Each new service inherits correct behavior instead of repeating the same mistakes and fixes. - Cheaper tuning. Rates and bursts change with a config reload rather than an application release.
limit_req_dry_runand$limit_req_statusin the access log let you check the effect of a change on real traffic before it rejects anyone. - Faster debugging. The "limiting requests" and "delaying request" log entries name the zone and excess, so it is quick to tell a throttled client from a failing backend. Returning 429 instead of 503 also keeps rate-limit rejections from paging on-call as an outage.
The savings shrink once you need exact quotas, fleet-wide counts or billing accuracy. At that point the work moves into a shared-state layer or the application, as the next two sections describe.
When should you avoid relying on Nginx rate limiting?
limit_req is a good first line of defense against bursts and crude abuse. It is a poor fit for anything that needs fairness, accuracy or accountability.
Per-IP keys misidentify clients. Keying on $binary_remote_addr treats everyone behind a NAT, corporate proxy or mobile carrier gateway as one client. That can be hundreds of real users sharing a single bucket. The same key does little against distributed abuse, because a botnet spreading requests across thousands of addresses stays under any per-IP limit.
State is local to each instance. Every Nginx node keeps its own shared-memory zone, and nodes do not synchronize. Behind a load balancer with N nodes, a client can get roughly N times the configured rate. The exact multiple depends on how traffic is distributed, so the effective limit shifts whenever you scale the fleet.
Zones have a fixed size. When a zone fills, Nginx evicts older entries to make room. Evicted clients start over with a fresh bucket. If Nginx still cannot allocate state for a new key, it rejects the request outright, even though that client never exceeded anything.
It counts requests, not cost. A cheap health check and an expensive report export each consume one token. To limit by cost, you need separate zones or location blocks per endpoint class.
It sends no rate-limit headers. Clients receive a status code but no remaining-quota or retry information unless you add those headers yourself.
These gaps get expensive when teams use limit_req for quota or billing enforcement. Customers expect exact counts, per-account keys, fleet-wide totals and headers they can program against. Each of those must be built around Nginx, typically with an authenticated key, a shared counter store and custom response logic. At that point the module has stopped being the enforcement mechanism.
What are the alternatives to limit_req?
Each alternative below measures something different, so the choice depends on what you are protecting.
| Approach | What it limits | Scope | Accuracy | Engineering effort |
|---|---|---|---|---|
limit_req |
Request rate per key | Single Nginx instance | Approximate per node | Low |
limit_conn |
Concurrent connections per key | Single Nginx instance | Exact per node | Low |
| Shared-state limiting layer | Request rate per key | Whole fleet | High, minus store latency | Medium to high |
| Application-level quotas | Usage per account or plan | Whole product | Highest | High |
| Edge or gateway limiting | Rate before traffic reaches origin | Network perimeter | Varies by provider | Low to medium |
limit_conn, configured with limit_conn_zone, caps how many connections a key holds open at once. It is the better tool when the expensive resource is concurrency rather than throughput, such as slow uploads, long-polling or streaming endpoints. A client sending few requests that each hold a worker for minutes will slip past limit_req but not limit_conn.
A shared-state layer keeps counters in a central store, so ten nodes enforce one limit rather than ten separate ones. In exchange, every request depends on a network call and on the store being available.
Application quotas belong where limits mean money or contract terms: per-API-key tiers, monthly allowances, and responses that tell clients how much quota remains.
Edge limiting absorbs volumetric floods before they consume your bandwidth.
A sensible default is to keep limit_req as the coarse first layer. Set it generously, keyed on IP, and use it to shed obvious abuse cheaply. Add limit_conn for long-lived endpoints. Move to shared or application-level enforcement only when per-node drift or billing accuracy actually costs you something.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to nginx limit_req burst nodelay, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.