What is Nginx rate limiting and how does limit_req work?
Nginx rate limiting is built from two directives. limit_req_zone sits in the http context and defines what is counted and how fast it may arrive. limit_req sits in a server or location block and applies that zone to traffic. API teams use the pair to cap how hard any single client can hit an upstream. A retry loop with no backoff, a misconfigured cron job or a credential-stuffing script then hits a ceiling at the edge, instead of exhausting application workers or database connections.
A zone definition has three parts:
- Key. Requests that share a key value share a bucket. Use
$binary_remote_addrrather than$remote_addr. The binary form is a fixed 4 bytes for IPv4 and 16 bytes for IPv6. The text form for IPv4 alone can be up to 15 bytes. A shorter key means each state takes less memory, so more clients fit in the zone. - Name and size. For example,
zone=api:10mcreates a shared memory area namedapiof 10 megabytes. All worker processes use it, so the limit applies per server, not per worker. - Rate. You set this in requests per second (
r/s) or per minute (r/m). For limits below one per second, user/m, such as30r/m.
Nginx enforces the rate as a leaky bucket tracked at millisecond granularity. 10r/s means one request every 100 ms. It does not mean ten requests allowed at the top of each second. Without a burst setting, a request that arrives 40 ms after the previous one is rejected, with a default status of 503. This catches teams off guard when real clients send small, legitimate clusters of requests.
A minimal working setup takes two lines:
- In
http:limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s; - Inside
location /api/:limit_req zone=api;
http {
# Key: client IP in binary form (4 bytes IPv4, 16 bytes IPv6) to save zone memory.
# Zone: shared memory area named "api", 10 MB, shared by all worker processes.
# Rate: 10r/s is enforced as one request every 100 ms, not ten per second boundary.
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
# Slower example for expensive endpoints: 30r/m works out to one request every 2 s.
limit_req_zone $binary_remote_addr zone=login:10m rate=30r/m;
upstream api_backend {
server 127.0.0.1:8080;
}
server {
listen 80;
server_name api.example.com;
location /api/ {
# No burst: a request arriving less than 100 ms after the previous one
# from the same IP is rejected (503 by default).
limit_req zone=api;
proxy_pass
}
location = /api/login {
limit_req zone=login;
proxy_pass
}
}
}
A minimal config that defines per-IP rate-limit zones in the http context and applies them to API locations. With no burst setting, any request arriving sooner than the configured interval is rejected.
How does it work, step by step?
For each request that reaches a location with limit_req, Nginx runs the check in its preaccess phase. That is before the request is proxied and before any upstream work happens. The sequence is:
- Evaluate the key. Nginx computes the zone's key variable for this request, such as
$binary_remote_addror amapoutput. If the key is empty, the request is not counted and passes through. - Look up the state. Nginx looks for that key in the zone's shared memory. If no state exists, it creates one. Because every worker process reads and writes the same zone, a client cannot avoid the limit by landing on a different worker.
- Drain and add. The stored state records how much "excess" the key has built up and when it last made a request. Nginx subtracts what has drained at the configured rate since then, and then adds one for the current request.
- Decide. If the new excess is within the rate, the request passes. If it exceeds the rate but fits inside
burst, the request is either delayed until its slot comes up or, withnodelayor under thedelaythreshold, passed immediately. If it would overflowburst, the request is rejected withlimit_req_status, which is 503 unless you change it. - Repeat for every limit. When a block has several
limit_reqdirectives, each zone goes through the same steps. The request must fit within all of them.
All of this happens inside Nginx with no external lookup. That is why it is cheap. It is also why the counters are local to one instance, which a later section covers.
Who should use Nginx rate limiting?
limit_req fits teams that already run Nginx in front of an API and want a cheap guardrail at the edge. It works best in these cases:
- Platform and SRE teams who own the reverse proxy and want to protect upstreams from runaway clients, retry storms and scripted abuse without waiting on application changes.
- Backend teams with endpoints that are easy to abuse, such as login, password reset, signup, OTP verification and search. A tight per-IP or per-key limit on these cuts off brute-force and scraping attempts early.
- Small and mid-sized deployments that run one or a few Nginx instances. Per-instance counters are accurate enough there, and adding a shared-store limiter would mean more moving parts than the problem warrants.
- Teams running several services in different languages behind one proxy layer. One configuration pattern can cover all of them, so each service doesn't need its own limiter library.
It is a weaker fit for billing-grade quotas, limits that must be exact across a large or autoscaling fleet, and APIs where request cost varies widely between endpoints. The last section covers alternatives for those cases.
How do burst, nodelay and delay change latency?
Each limit_req key gets a bucket that drains at the configured rate. burst is the bucket's capacity. Requests that fit are queued and released at the configured rate, not rejected. Rejection only starts when the bucket overflows. Without burst, any request that arrives faster than the rate allows is refused.
A worked timeline
Illustrative estimate. Assume rate=10r/s, which means one slot drains every 100 ms. Assume burst=5. Eight requests from one fresh client arrive at t=0.
| Request | burst=5 |
burst=5 nodelay |
burst=5 delay=3 |
|---|---|---|---|
| 1 | served at 0 ms | served at 0 ms | served at 0 ms |
| 2–4 | served at 100, 200, 300 ms | served at 0 ms | served at 0 ms |
| 5–6 | served at 400, 500 ms | served at 0 ms | served at 100, 200 ms |
| 7–8 | rejected | rejected | rejected |
nodelay does not make the bucket bigger. It forwards queued requests immediately, but their slots stay occupied and drain at 10 r/s. In the example, a ninth request at t=50 ms is rejected because no slot has freed yet. One slot frees at t=100 ms. delay=N is the middle option: the first N excess requests pass without waiting, and the rest are paced.
The trade-off
Queuing smooths load on the upstream. The cost is that each delayed request holds a client connection, a worker slot, and possibly an upstream keepalive connection while it waits. If the burst is large, the wait can exceed a client's timeout. The client then retries and adds more load. nodelay keeps latency flat, but the full spike reaches the backend at once.
A common choice is delay with a small N. This absorbs the short request clusters typical clients send without making most of them wait.
limit_req_zone $binary_remote_addr zone=api_per_ip:10m rate=10r/s;
upstream api_backend {
server 10.0.0.10:8080; # placeholder backend
keepalive 32;
}
server {
listen 80;
server_name api.example.com;
# Return 429 instead of the default 503 when the bucket overflows.
limit_req_status 429;
# Option A: queue the excess. Up to 5 extra requests wait and are released
# every 100 ms. Upstream load is smooth, but waiting clients hold connections.
location /v1/reports/ {
limit_req zone=api_per_ip burst=5;
proxy_pass
}
# Option B: forward the excess immediately. Latency stays flat, but the whole
# spike reaches the backend. Slots still drain at 10 r/s, so a follow-up
# request is rejected until a slot frees.
location /v1/search/ {
limit_req zone=api_per_ip burst=5 nodelay;
proxy_pass
}
# Option C: middle ground. A small cluster of excess requests passes without
# waiting, and anything beyond delay=3 is paced at the configured rate.
location /v1/ {
limit_req zone=api_per_ip burst=5 delay=3;
proxy_pass
}
}
The same 10 r/s per-IP zone is applied with burst only, burst with nodelay, and burst with delay=3, so each location shows a different trade-off between queuing latency and backend spikes.
How do you get the real client IP behind a load balancer or CDN?
Without the realip module, $remote_addr is the address of the TCP peer that connected to Nginx. Behind a load balancer, that peer is the load balancer itself. A zone keyed on $binary_remote_addr then puts every client into the same handful of buckets, one per balancer node. One busy client can trigger 429s for everyone.
client 203.0.113.7
│ X-Forwarded-For: (whatever the client sends)
▼
CDN edge 198.51.100.10 sees peer 203.0.113.7, appends it
▼
load balancer 10.0.1.5 sees peer 198.51.100.10, appends it
▼
Nginx sees peer 10.0.1.5
X-Forwarded-For: 203.0.113.7, 198.51.100.10
The realip module replaces $remote_addr with a value taken from a header. It only does this when the connecting peer matches a set_real_ip_from range.
set_real_ip_fromlists the address ranges you trust. In this example, those are the load balancer subnet and the CDN's published egress ranges.real_ip_headernames the header to read. This is usuallyX-Forwarded-For, or the single-value client header your CDN documents.real_ip_recursive onwalksX-Forwarded-Forfrom right to left. It skips trusted addresses and stops at the first untrusted one, which is 203.0.113.7 here. With it off, Nginx takes the rightmost entry, which is the CDN edge.
Clients control whatever they put at the left of X-Forwarded-For. If the trusted ranges are too broad, for example a whole public block or 0.0.0.0/0, Nginx keeps walking left into those forged values. Attackers can then rotate fake IPs to dodge limits, or use a victim's address to get that user throttled.
If the trusted ranges are too narrow, nothing visibly breaks. Suppose you trust the load balancer but not the CDN. Nginx stops walking at a CDN edge address, so all users behind that edge share one bucket and get throttled together.
http {
# Trust only the hops we control or that our CDN documents.
# Load balancer subnet (internal):
set_real_ip_from 10.0.1.0/24;
# CDN egress range (placeholder; use the CDN's published list):
set_real_ip_from 198.51.100.0/24;
# Never add 0.0.0.0/0 or a broad public block here: Nginx would
# keep walking left into client-forged X-Forwarded-For entries.
# Read the client address from X-Forwarded-For.
real_ip_header X-Forwarded-For;
# Walk right to left, skip trusted addresses, stop at the first
# untrusted one (203.0.113.7 in the diagram). With this off,
# Nginx would take the rightmost entry, the CDN edge.
real_ip_recursive on;
# $binary_remote_addr now holds the rewritten client address,
# so each client gets its own bucket instead of sharing the LB's.
limit_req_zone $binary_remote_addr zone=api_per_ip:10m rate=10r/s;
# Optional: log both values to catch a too-narrow trust list.
# If client_ip shows your CDN or LB addresses, everyone shares a bucket.
log_format realip '$remote_addr peer=$realip_remote_addr '
'xff="$http_x_forwarded_for" status=$status';
server {
listen 80;
access_log /var/log/nginx/api_access.log realip;
location /api/ {
limit_req zone=api_per_ip burst=20 nodelay;
limit_req_status 429;
proxy_pass
}
}
}
Trusting only the load balancer subnet and CDN egress range with set_real_ip_from, reading X-Forwarded-For recursively so limit_req keys on the real client address, and logging $realip_remote_addr alongside it to spot a trust list that is too narrow.
Which key should you rate limit on: IP, API key or user?
That shared bucket is the core weakness of keying on $binary_remote_addr. An IP address identifies a network path, not a client. Offices behind one corporate proxy, homes behind carrier-grade NAT and phones behind a mobile carrier gateway all share an address, so one heavy user throttles everyone on that path. An attacker with a few thousand rotating addresses gets the reverse result and stays under every per-IP limit.
For APIs, a credential is usually a better key. Use limit_req_zone $http_x_api_key ... to key on the raw header. A map can also normalise or validate it first, for example by rejecting values that don't match your key format. For per-user limits, have an auth_request subrequest return the user ID, capture it with auth_request_set, and use that variable as the key.
Nginx does not count requests whose key evaluates to an empty string. You can use this to exempt traffic. Map /healthz to an empty value, or use geo to flag internal CIDRs and feed that flag into a map that outputs an empty key. Exempt traffic then never touches the zone.
Unauthenticated requests also produce an empty key. To keep them limited, fall back to the client IP in the same map.
| Key | Accuracy | Spoofability | Setup required |
|---|---|---|---|
| Client IP | Low: shared NAT merges clients, botnets split one | Low only if real-IP trust is correct | real_ip_header and trusted ranges |
| API key | High per integration | Anyone can send a header. Unvalidated random values each get a fresh bucket | Header variable, ideally validated |
| User ID | Highest per person | Only as strong as your auth | Auth subrequest or trusted upstream header |
set_real_ip_from 10.0.0.0/8; # your load balancer range (placeholder)
real_ip_header X-Forwarded-For;
real_ip_recursive on;
geo $is_internal {
default 0;
10.20.0.0/16 1; # internal services (placeholder)
192.168.0.0/16 1;
}
map $http_x_api_key $api_key_valid {
default "";
"~^[A-Za-z0-9_-]{32}$" $http_x_api_key;
}
map $api_key_valid $client_key {
"" $binary_remote_addr;
default "key:$api_key_valid";
}
map $uri $key_by_path {
/healthz "";
default $client_key;
}
map $is_internal $limit_key {
1 "";
default $key_by_path;
}
limit_req_zone $limit_key zone=api:10m rate=10r/s;
server {
listen 80;
location / {
limit_req zone=api burst=20 nodelay;
limit_req_status 429;
proxy_pass
}
}
Chained geo and map blocks build one rate-limit key. Validated API keys get their own bucket, and missing or malformed keys fall back to the real client IP. Health checks and internal CIDRs get an empty key so nginx never counts them.
How do you layer limits and size the shared memory zone?
You can put several limit_req directives in the same block, and every one of them applies. A request goes through only if it fits within all of them, and the most restrictive limit decides any delay or rejection. A typical setup combines a per-IP zone keyed on $binary_remote_addr with a per-API-key zone. The IP zone catches unauthenticated floods, and the key zone stops one customer from spreading load across many addresses. You can also give login, password reset and expensive search endpoints a tight limit while the rest of the API gets a looser one.
Inheritance is easy to get wrong. A location inherits limit_req directives from the enclosing level only if it defines none of its own. If you add a strict limit_req to location /login and leave out the global per-IP limit, that location silently loses the global limit. Repeat every limit you still want inside that location.
Size each zone from the number of unique keys you expect it to track at once. As an illustrative estimate, assume each state takes about 128 bytes (variable-length keys such as API keys cost more than a binary IPv4 address) and assume 500,000 active keys. That comes to roughly 64 MB, plus some headroom.
When a zone fills, Nginx evicts the least recently used states. If it still cannot allocate a new state, it rejects the request with an error. Attackers can use this: a flood of random API keys or spoofed headers creates fresh states that push out legitimate ones and reset their counters. Oversizing the zone has its own cost, because each Nginx host reserves the full allocation.
How do you return 429, observe and test rate limits safely?
Start by changing the rejection code. By default limit_req returns 503, which tells clients and monitors that the service is broken rather than that the caller is over quota. Set limit_req_status 429 so dashboards separate throttling from real outages. limit_req_log_level sets the severity for rejected requests. Delayed requests are logged one level lower, so warn for rejections puts delays at notice. That lets you filter "delaying request" entries apart from "limiting requests" entries, each of which names the zone, the excess value and the client.
Nginx does not add Retry-After for you. Serve 429s through an error_page location that adds the header with always, and document a single policy for clients: honour the header, back off with jitter, and never retry immediately. If you skip this, clients that retry in tight loops increase the overload that triggered the limit.
Where your build supports limit_req_dry_run, deploy new limits in dry-run mode first. Nginx logs the requests it would have rejected without blocking them. Log $limit_req_status, if your build provides it, so you can count would-be rejections per key against real traffic. This staged rollout replaces guessed numbers with measured ones and prevents incidents where a new limit cuts off a legitimate batch client.
To test, run a curl loop that prints only status codes. Then use a load generator that sends requests at a fixed rate above your limit. Check the counts against the zone settings. For example, with assumed values of 10r/s and burst=20 (illustrative estimate), a fast burst should get about 21 successes and then roughly 10 per second.
Finally, confirm reload behaviour on your own build. A reload that changes a zone's size, rate or key can reset or disturb its counters.
How can Nginx rate limiting save engineering time?
Most of the time saved comes from work you no longer have to do in each service, and from incidents that stop at the edge.
- No limiter code per service. A limit is a few lines of proxy configuration, so teams don't each choose, integrate and maintain a limiter library in their own language. One reviewed pattern, such as the key-building
mapchain above, can be reused across every API behind the proxy. - Faster incident response. When a misbehaving client or retry storm hits, an operator can add or tighten a limit for one location and reload Nginx. This takes no application build or deploy. It is often the quickest way to stabilise an upstream while the root cause is investigated.
- Fewer overload incidents to debug. Runaway cron jobs, retry loops without backoff and brute-force attempts get 429s at the proxy, before they exhaust application workers or database connections. Engineers spend less time tracing cascading failures back to a single noisy caller.
- Lower-risk rollouts. Dry-run mode and the separate log messages for delayed and rejected requests let you check a new limit against real traffic before enforcing it. That replaces trial-and-error tuning in production and the rollback work that follows a bad guess.
- Clearer on-call signals. Returning 429 instead of 503 means throttling shows up as quota pressure on dashboards, not as an outage. On-call engineers don't get paged into investigating backends that are healthy.
How much time this saves depends on how many services sit behind the proxy and how often overload incidents happen today. Measure your own incident and rollout history rather than assuming a figure.
When should you avoid limit_req, and what are the alternatives?
limit_req keeps its counters in shared memory on a single Nginx instance. Nothing is synchronised between nodes, so if you run four instances behind a load balancer with rate=10r/s, a client spread evenly across them can get roughly 40 requests per second. You can divide the rate by the node count, but that breaks whenever you scale out, lose a node, or the balancer distributes traffic unevenly.
The module also counts requests, not cost. A cached health check and a report export that scans millions of rows each use one slot. If a few endpoints dominate your backend load, a request-rate limit either lets those calls overload the service or throttles cheap traffic that was never a problem.
| Approach | Scope | Measures | Adoption cost |
|---|---|---|---|
limit_req |
Per Nginx instance | Request rate | Low: config only |
limit_conn |
Per Nginx instance | Concurrent connections | Low: config only |
| App limiter with shared store | Global across nodes | Rate, quotas, custom units | Medium: new dependency, failure modes, latency per check |
| API gateway or edge limits | Global or per point of presence | Rate, often per key | Medium to high: new layer to run or pay for |
| Cost or concurrency limits in the service | Per service | Work done, in-flight load | High: needs per-endpoint cost model |
limit_req alone is enough when you run one or a few instances, need abuse protection more than exact quotas, and your endpoints cost roughly the same. Move to a coordinated approach when limits are part of a customer contract, when your node count changes often, or when a small number of expensive calls drive most of your load. Keep limit_req in front of the coordinated limiter as a cheap first line of defence.
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 rate limiting, 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.