APIs · Intermediate · 20 min
How to Rate Limit an API with Nginx
By Padding · Updated 16 Nov 2026
Ubuntu 26.04.1 LTS · Nginx 1.30
You will put request limits in front of a small API with Nginx 1.30 on Ubuntu 26.04, give the login route a stricter limit than the rest, return a proper 429 response with Retry-After, exempt a trusted address, and watch every limit work with real requests.
On this page
Any API that is open to the internet gets more requests than you planned for: a script stuck in a loop, a scraper, or someone guessing passwords on your login route. Rate limiting puts a ceiling on how fast one client can call you, and it works best before the request reaches your application. Nginx has it built in, in the module ngx_http_limit_req_module, and it answers refused requests in microseconds.
In this tutorial you run a tiny API on 127.0.0.1:9000, put Nginx in front of it on 127.0.0.1:8080, and add limits step by step. Each limit is tested with a burst of requests, so you see the numbers: how many get 200 and how many get 429 Too Many Requests. Everything listens on the loopback address, so nothing is exposed to the internet while you experiment. Nginx's own reference for the directives is https://nginx.org/en/docs/http/ngx_http_limit_req_module.html.
Step 1 · Run a small API
Install Nginx first as in the Nginx install tutorial, then check you have the tools:
sudo apt update
sudo apt install -y curl python3
nginx -vThe last command prints nginx version: nginx/1.30. followed by the patch number.
Write the API. It has a GET /api/hello route that returns JSON and a POST /login route that always answers 401, which is all you need to test limits on a login route:
mkdir -p ~/ratelimit-demo
cat > ~/ratelimit-demo/ratelimit-backend.py <<'PY'
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
class Handler(BaseHTTPRequestHandler):
def send_json(self, status, payload):
body = json.dumps(payload).encode()
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def do_GET(self):
if self.path == "/api/hello":
self.send_json(200, {"message": "hello"})
else:
self.send_json(404, {"error": "not found"})
def do_POST(self):
length = int(self.headers.get("Content-Length", 0))
self.rfile.read(length)
if self.path == "/login":
self.send_json(401, {"error": "wrong password"})
else:
self.send_json(404, {"error": "not found"})
def log_message(self, *args):
pass
ThreadingHTTPServer(("127.0.0.1", 9000), Handler).serve_forever()
PY
nohup python3 ~/ratelimit-demo/ratelimit-backend.py > /dev/null 2>&1 &
sleep 1
curl -s -w '\n' http://127.0.0.1:9000/api/helloThe output is {"message": "hello"}.
Step 2 · Limit requests per client address
A limit has two parts. A zone is shared memory in which Nginx remembers how recently each client called. A limit_req line in a location applies a zone. Write both in a new file in /etc/nginx/conf.d/, which the packaged Nginx includes inside its http block:
sudo tee /etc/nginx/conf.d/ratelimit.conf > /dev/null <<'NGINX'
limit_req_zone $binary_remote_addr zone=api:10m rate=5r/s;
limit_req_status 429;
limit_req_log_level warn;
server {
listen 127.0.0.1:8080;
location /api/ {
limit_req zone=api burst=10 nodelay;
proxy_pass http://127.0.0.1:9000;
}
}
NGINX
sudo nginx -tnginx -t ends with syntax is ok and test is successful. What each part does:
$binary_remote_addris the client's IP address in a compact form, so one client is one bucket. A 10 MB zone holds roughly 160,000 addresses.rate=5r/sis the steady rate: one request every 200 milliseconds per client. Nginx tracks it in milliseconds, so it enforces the average, not "5 in each wall-clock second".burst=10lets a client go above the rate briefly. Up to 10 extra requests are accepted, and anything past that is refused. Real clients are bursty: a page that loads five API calls at once is normal.nodelaymakes the burst requests go through at once. Without it, Nginx holds them back and releases them at the steady rate, so a client in a burst waits. That smooths traffic but makes honest users slow.nodelayis the right choice for an API.limit_req_status 429makes refused requests answer429 Too Many Requests. The default is503, which looks like a server fault to monitoring and clients.
Apply the configuration without dropping connections:
sudo systemctl reload nginxCheck it worked
Send 20 requests as fast as curl can, and count the status codes:
for i in $(seq 1 20); do
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/api/hello
done | sort | uniq -cThe first request passes, ten more fit in the burst, and the rest are refused. You see about 11 200 and 9 429. If your loop is slow, one more request can slip through as the bucket refills. Wait a few seconds before you run it again, because the bucket refills at 5 per second.
Nginx writes each refusal to its error log:
sudo grep 'limiting requests' /var/log/nginx/error.log | tail -n 2Each line has limiting requests, excess: 10. followed by a fraction, and names the zone api and the client address. The warn level you set with limit_req_log_level is what puts them in the log.
Step 3 · Return a useful 429 response
A bare 429 tells a well-behaved client to slow down, but not for how long. The standard header for that is Retry-After. Add an error page for status 429 that returns JSON and the header. The always keyword is needed, because Nginx otherwise only adds headers to successful responses:
sudo tee /etc/nginx/conf.d/ratelimit.conf > /dev/null <<'NGINX'
limit_req_zone $binary_remote_addr zone=api:10m rate=5r/s;
limit_req_status 429;
limit_req_log_level warn;
server {
listen 127.0.0.1:8080;
error_page 429 = @too_many;
location @too_many {
default_type application/json;
add_header Retry-After 1 always;
return 429 '{"error":"rate limit exceeded"}\n';
}
location /api/ {
limit_req zone=api burst=10 nodelay;
proxy_pass http://127.0.0.1:9000;
}
}
NGINX
sudo nginx -tReload Nginx as before. Then use up the burst and look at the refused response in full:
for i in $(seq 1 15); do curl -s -o /dev/null http://127.0.0.1:8080/api/hello; done
curl -si http://127.0.0.1:8080/api/helloThe first line is HTTP/1.1 429 Too Many Requests. The headers include Content-Type: application/json and Retry-After: 1, and the body is {"error":"rate limit exceeded"}. Nginx cannot know how long this client must wait, so 1 is a reasonable constant for a rate of five per second.
Step 4 · Give the login route a stricter limit
Browsing an API can be fast, but a person logging in does not need to try more than a few times a minute. A script guessing passwords does. Add a second zone for /login, keyed on the same client address but with a much lower rate. rate=6r/m is one request every ten seconds, with a burst of three:
sudo tee /etc/nginx/conf.d/ratelimit.conf > /dev/null <<'NGINX'
limit_req_zone $binary_remote_addr zone=api:10m rate=5r/s;
limit_req_zone $binary_remote_addr zone=login:10m rate=6r/m;
limit_req_status 429;
limit_req_log_level warn;
server {
listen 127.0.0.1:8080;
error_page 429 = @too_many;
location @too_many {
default_type application/json;
add_header Retry-After 10 always;
return 429 '{"error":"rate limit exceeded"}\n';
}
location /api/ {
limit_req zone=api burst=10 nodelay;
proxy_pass http://127.0.0.1:9000;
}
location = /login {
limit_req zone=login burst=3 nodelay;
proxy_pass http://127.0.0.1:9000;
}
}
NGINX
sudo nginx -tReload Nginx, then make eight login attempts in a row:
for i in $(seq 1 8); do
curl -s -o /dev/null -w '%{http_code}\n' -X POST --data 'username=a&password=b' http://127.0.0.1:8080/login
done | sort | uniq -cThe first request and three burst requests reach the API and get 401 from it. The other four never reach it and get 429: 4 401 and 4 429. An attacker is now limited to roughly one guess every ten seconds per address, after a small allowance.
This limit is per IP address. An attacker with many addresses is not slowed by it, and one account can be attacked from many places. Pair it with limits in your application per username, as in add JWT authentication to a FastAPI API, and with Fail2ban for repeat offenders.
Step 5 · Let a trusted address through
You may want your own monitoring, an office or a partner's server to skip the limit. The documented way is to make the key empty for them, because Nginx does not count requests whose key is empty. A geo block decides who is trusted, and a map turns that into the key. This example trusts 127.0.0.2, a second loopback address you can test from. Replace it with the real address or network, such as 203.0.113.0/24.
The zone has a new name, api_v2, on purpose. A zone remembers its key in shared memory. If you keep the name api but change the key, nginx -t still says the file is fine, but the reload fails with an error like limit_req "api" uses the "$api_limit_key" key while previously it used the "$binary_remote_addr" key, and Nginx keeps running the old configuration. Whenever you change a zone's key, give it a new name, and watch sudo tail /var/log/nginx/error.log after a reload.
sudo tee /etc/nginx/conf.d/ratelimit.conf > /dev/null <<'NGINX'
geo $rate_limited {
default 1;
127.0.0.2 0;
}
map $rate_limited $api_limit_key {
0 "";
1 $binary_remote_addr;
}
limit_req_zone $api_limit_key zone=api_v2:10m rate=5r/s;
limit_req_zone $binary_remote_addr zone=login:10m rate=6r/m;
limit_req_status 429;
limit_req_log_level warn;
server {
listen 127.0.0.1:8080;
error_page 429 = @too_many;
location @too_many {
default_type application/json;
add_header Retry-After 10 always;
return 429 '{"error":"rate limit exceeded"}\n';
}
location /api/ {
limit_req zone=api_v2 burst=10 nodelay;
proxy_pass http://127.0.0.1:9000;
}
location = /login {
limit_req zone=login burst=3 nodelay;
proxy_pass http://127.0.0.1:9000;
}
}
NGINX
sudo nginx -tReload Nginx and send 20 requests from each address. --interface makes curl use 127.0.0.2 as its source address:
echo "from 127.0.0.1:"
for i in $(seq 1 20); do
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/api/hello
done | sort | uniq -c
echo "from 127.0.0.2:"
for i in $(seq 1 20); do
curl -s -o /dev/null --interface 127.0.0.2 -w '%{http_code}\n' http://127.0.0.1:8080/api/hello
done | sort | uniq -cThe first address is limited as before: about 11 200 and 9 429. The trusted address gets 20 200.
Step 6 · Check what Nginx sees as the client address
Everything above depends on one thing: $remote_addr must be the real client. If another proxy, a CDN or a load balancer sits in front of this Nginx, $remote_addr is that proxy's address, and every user shares one bucket. One heavy user then locks out everybody, and your limit is useless.
In that setup, tell Nginx which addresses it may trust to report the real client, and which header carries it. This is the ngx_http_realip_module. The addresses here are examples to replace:
set_real_ip_from 203.0.113.10; # replace: your load balancer or proxy
real_ip_header X-Forwarded-For;
real_ip_recursive on;Only list addresses you control. If you trust a header from anyone, a client can invent its own address and get a fresh bucket on every request. Also never key a limit on a header the client sets, such as X-Api-Key, unless you check that the key is valid first.
For roll-outs, limit_req_dry_run on; in a location counts and logs excess requests without refusing any, so you can watch the logs for a day and see who a new limit would affect before you enforce it.
Step 7 · Choose limits that fit your API
Start from measured traffic, not from a guess:
- Check your access log for the busiest honest clients, and set the rate above that with room to spare. A limit that blocks real users costs more than the abuse it stops.
- Use a low rate with a modest burst for expensive routes (search, report export, login) and a higher rate for cheap ones.
- Keep
limit_req_log_levelatwarnfor the first weeks, so you can see who is limited. - Also limit concurrent connections with
limit_conn_zoneandlimit_conn(see https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html) if slow clients holding connections open is your problem. - Return
429and aRetry-Afterheader, so clients that respect them back off.
Troubleshooting
"limit_req_zone" directive is not allowed here: thelimit_req_zoneline must sit in thehttpblock, not insideserverorlocation. A file in/etc/nginx/conf.d/is already inside it.zero size shared memory zoneorzone ... not found: the zone name inlimit_reqmust match one thatlimit_req_zonedefines.- Every request is limited even for one client:
$remote_addris your proxy, as in the previous step. - You still see
503instead of429:limit_req_status 429;is missing or in the wrong block, or the reload did not run. Runsudo nginx -tand reload again. - Nothing is limited: check that
limit_reqis in thelocationthat matches your path.location = /loginmatches only that exact path.
Step 8 · Stop the demo and clean up
Remove the configuration file and reload Nginx so it forgets the limits. Then stop the API and delete its folder:
sudo rm /etc/nginx/conf.d/ratelimit.conf
sudo nginx -t
sudo systemctl reload nginx
pkill -f ratelimit-backend.py
rm -rf ~/ratelimit-demoNginx itself keeps running with its default site. If you want it gone too, see the Nginx install tutorial.
Next steps
- Protect the login code itself: add JWT authentication to a FastAPI API.
- Put the API behind HTTPS: free HTTPS with Let's Encrypt and Nginx.
- Add response headers that protect browsers: add security headers in Nginx.
- Ban repeat offenders at the firewall: block brute-force logins with Fail2ban.
Related tutorials
- How to Install Nginx on Ubuntu 26.04You will install the current stable Nginx 1.30 from the official nginx.org repository on Ubuntu 26.04, serve its test page, and learn where its files live and how to reload it safely.
- How to Put Nginx in Front of a Node.js App as a Reverse ProxyYou will install Node.js 26, run a small app on a local port, and configure Nginx 1.30 to pass public traffic to it with the headers your app needs.
- How to Test and Debug an API with curlYou will write a small practice API, then call it with curl 8 to read responses and headers, send JSON, send an authorization header without putting the secret on the command line, follow redirects, measure timing, set timeouts and retries, and read curl's verbose output when a request goes wrong.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials