Skip to main content

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:

Bash
sudo apt update
sudo apt install -y curl python3
nginx -v

The 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:

Bash
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/hello

The 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:

Bash
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 -t

nginx -t ends with syntax is ok and test is successful. What each part does:

  • $binary_remote_addr is 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/s is 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=10 lets 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.
  • nodelay makes 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. nodelay is the right choice for an API.
  • limit_req_status 429 makes refused requests answer 429 Too Many Requests. The default is 503, which looks like a server fault to monitoring and clients.

Apply the configuration without dropping connections:

Bash
sudo systemctl reload nginx

Check it worked

Send 20 requests as fast as curl can, and count the status codes:

Bash
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

The 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:

Bash
sudo grep 'limiting requests' /var/log/nginx/error.log | tail -n 2

Each 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:

Bash
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 -t

Reload Nginx as before. Then use up the burst and look at the refused response in full:

Bash
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/hello

The 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:

Bash
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 -t

Reload Nginx, then make eight login attempts in a row:

Bash
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 -c

The 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.

Bash
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 -t

Reload Nginx and send 20 requests from each address. --interface makes curl use 127.0.0.2 as its source address:

Bash
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 -c

The 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:

Nginx
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_level at warn for the first weeks, so you can see who is limited.
  • Also limit concurrent connections with limit_conn_zone and limit_conn (see https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html) if slow clients holding connections open is your problem.
  • Return 429 and a Retry-After header, so clients that respect them back off.

Troubleshooting

  • "limit_req_zone" directive is not allowed here: the limit_req_zone line must sit in the http block, not inside server or location. A file in /etc/nginx/conf.d/ is already inside it.
  • zero size shared memory zone or zone ... not found: the zone name in limit_req must match one that limit_req_zone defines.
  • Every request is limited even for one client: $remote_addr is your proxy, as in the previous step.
  • You still see 503 instead of 429: limit_req_status 429; is missing or in the wrong block, or the reload did not run. Run sudo nginx -t and reload again.
  • Nothing is limited: check that limit_req is in the location that matches your path. location = /login matches 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:

Bash
sudo rm /etc/nginx/conf.d/ratelimit.conf
sudo nginx -t
sudo systemctl reload nginx
pkill -f ratelimit-backend.py
rm -rf ~/ratelimit-demo

Nginx itself keeps running with its default site. If you want it gone too, see the Nginx install tutorial.

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.