← Blog
A lavender turnstile with three orange arms controls entry.
Published on
2026-11-18

Nginx rate limiting: bursts, delays, and HTTP 429

Nginx rate limiting controls how quickly requests reach an application for a chosen key, such as a client IP address. The useful question is what happens when traffic arrives unevenly: which requests pass immediately, which wait, and which receive an error?

This guide uses a small local backend to make those decisions visible. With a rate of two requests per second and a burst allowance of two, our fresh four-request burst produced three HTTP 200 responses followed by HTTP 429. We also checked delays, recovery, dry-run logging, and forged forwarding headers.

The examples passed 21 functional checks using Nginx 1.31.8 and Python 3.12.14 on Windows. They do not measure server capacity. Nginx documents limitations in its Windows build; validate your actual production platform and workload separately. If you are still choosing a proxy, start with Caddy vs Nginx.

Choose what the limit should count

Start with the operation you want to protect. A search endpoint that runs an expensive database query may need a different policy from a small health check. Decide whose requests share an allowance before choosing a number.

Per-IP limits can group unrelated users behind an office gateway or mobile network. They also cannot express an authenticated customer's monthly allowance. For account quotas, apply a policy after identity has been established. Keep request admission separate from job concurrency, payload size, and the cost of each operation.

The Nginx request-limit reference defines the shared zone, rate, and burst controls. Our example uses $binary_remote_addr as its key. burst=2 permits excess requests within the configured allowance; nodelay lets accepted excess requests proceed immediately. Neither setting raises the sustained rate.

Build an isolated local example

Create a new working directory containing logs and temp subdirectories. Save the following as nginx.conf. It listens only on your own computer, on port 18082, and forwards to port 19001. Leave those ports free and keep this configuration separate from an existing Nginx service.

worker_processes 1;
pid logs/nginx.pid;
error_log logs/error.log info;

events { worker_connections 128; }

http {
    log_format limits '$request_uri $remote_addr $status $limit_req_status';
    access_log logs/access.log limits;

    limit_req_zone $binary_remote_addr zone=api:1m rate=2r/s;
    limit_req_zone $binary_remote_addr zone=paced:1m rate=2r/s;
    limit_req_zone $binary_remote_addr zone=observe:1m rate=2r/s;

    server {
        listen 127.0.0.1:18082;
        server_name localhost;
        limit_req_status 429;
        limit_req_log_level notice;

        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout 2s;
        proxy_read_timeout 2s;

        location = /healthz { return 204; }

        location /api/ {
            limit_req zone=api burst=2 nodelay;
            proxy_pass http://127.0.0.1:19001;
        }
        location /paced/ {
            limit_req zone=paced burst=2;
            proxy_pass http://127.0.0.1:19001;
        }
        location /dry/ {
            limit_req zone=observe burst=2 nodelay;
            limit_req_dry_run on;
            proxy_pass http://127.0.0.1:19001;
        }
    }
}

The three locations use separate zones so one experiment does not consume another's allowance. /api/ accepts a short burst without pacing it, /paced/ lets us observe delays, and /dry/ observes excess traffic without enforcing rejection. The readiness URL is deliberately outside these experiments.

Save this backend as backend.py and run python backend.py in another terminal. It is a local test fixture, not an application server for public use.

"""Local fixture only; not a production application server."""
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = json.dumps({'path': self.path, 'forwarded_for': self.headers.get('X-Forwarded-For')}).encode()
        self.send_response(200)
        self.send_header('Content-Type', 'application/json')
        self.send_header('Content-Length', str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, *args):
        pass

if __name__ == '__main__':
    ThreadingHTTPServer(('127.0.0.1', 19001), Handler).serve_forever()

Use your Nginx executable and the absolute path of the working directory. The commands below show a Windows example with Nginx available on PATH; replace C:/nginx-lab/ with your directory, retaining the trailing slash. The command-line reference explains the prefix and configuration options.

nginx -p C:/nginx-lab/ -c nginx.conf -t
nginx -p C:/nginx-lab/ -c nginx.conf

Run the second command only after the syntax check succeeds. Keep the backend running. The proxy configuration sends requests to that backend and replaces its forwarding headers with values from this direct client connection.

Send a burst and inspect what happened

Save the following as probe.py and run python probe.py. Give the allowance time to drain before repeating it; our checks waited 1.7 seconds between the independent burst cases. Every request here targets the local fixture.

import http.client
import json
import time

def request(path, headers=None):
    connection = http.client.HTTPConnection('127.0.0.1', 18082, timeout=5)
    started = time.monotonic()
    try:
        connection.request('GET', path, headers=headers or {})
        response = connection.getresponse()
        body = response.read().decode()
        return {'status': response.status,
                'seconds': round(time.monotonic() - started, 4),
                'body': body}
    finally:
        connection.close()

def run_burst():
    return [request('/api/burst?i=' + str(i)) for i in range(4)]

if __name__ == '__main__':
    for result in run_burst():
        print(json.dumps({'status': result['status'],
                          'seconds': result['seconds']}))

Our runner uses the same request function and burst sequence. These were the observed results with the configuration above:

Local checkObserved response
Three requests spaced 0.6 seconds apart200, 200, 200; PASSED
Four requests in a fresh immediate burst200, 200, 200, 429
Request after waiting 1.7 seconds200
Four different forged forwarding headers200, 200, 200, 429; same client address
Three sequential requests to /paced/All 200; first PASSED, next two DELAYED
Six immediate requests to /dry/All 200; REJECTED_DRY_RUN also appears in logs

The paced sequence took approximately half a second for each of its two delayed responses. That timing demonstrates the configured pacing in this fixture, not expected latency for a real API. Scheduling and other activity can change measurements or allow additional requests through a supposedly immediate burst.

Read logs/access.log to distinguish an allowed request from a delayed one. The test recorded PASSED, DELAYED, REJECTED, and REJECTED_DRY_RUN. Its custom access-log format includes both the HTTP status and the limiter's decision, so an HTTP 200 in dry-run mode does not hide a would-be rejection.

The test logs include full request URLs for inspection. Before adapting them to an application, remove sensitive query values and set an appropriate retention policy. A useful diagnostic log should not become a copy of credentials or private user input.

Return HTTP 429 deliberately

HTTP 429 means too many requests. This example selects it explicitly with limit_req_status 429; the module's default rejection status is 503. Do not assume that configuring a limiter automatically gives clients the response contract your API needs.

Our rejection contains Nginx's default error body and no application-specific retry advice. If clients require JSON, implement and test that response separately. The standard permits a Retry-After header, but any value you provide must fit your policy. A hard-coded delay is not an exact prediction of a shared allowance when other requests can consume it.

Client retries need a bound. Repeated immediate retries can keep an allowance exhausted, and repeating a write operation without understanding its outcome can create a separate application problem. Define retry behavior with the endpoint's owner.

Check the client address before trusting the result

We sent four requests with four different X-Forwarded-For values. They still shared the actual loopback address and produced 200, 200, 200, then 429. The successful backend responses also reported the loopback address. This checks the direct-client configuration shown here.

Behind a load balancer, the immediate connection address may identify the balancer instead of the visitor. Review the real-IP module and configure only the proxy addresses you actually trust. Do not use an arbitrary client-supplied forwarding header as the limit key.

The local test did not exercise a trusted-proxy chain. Before deployment, send requests through your real ingress path and verify both the address Nginx uses and the backend headers. Include a spoofed-header case. Check that the backend cannot be reached through a public route that bypasses the proxy policy.

Roll out with observations and a rollback

Choose an initial rate from a representative workload, including normal bursts. Watch legitimate-user failures, backend saturation, and response times together. A quieter backend can still accompany a broken user experience if the limiter rejects ordinary clients.

Use dry run to inspect decisions before enforcement. Review the policy on each protected location, validate the configuration, and test the change privately. Nginx supports configuration reloads and graceful shutdown; keep the previously working configuration available for rollback.

For this local exercise, stop Nginx with the same prefix and configuration path, then stop the Python backend with Ctrl+C:

nginx -p C:/nginx-lab/ -c nginx.conf -s quit

Do not carry the demonstration's two-requests-per-second setting into production as a sizing recommendation. An IP-based request count does not establish account fairness, distributed quotas, authentication, or protection from every form of abuse. For multiple independent proxy instances, decide how a shared allowance will be enforced instead of assuming their local state is global.

Connect the policy to the hosting decision

Once the admission policy works, test the application under the traffic you intend to allow. Measure the real endpoint's CPU use, memory use, database behavior, and latency. A reverse proxy does not remove those capacity requirements.

Compare API hosting models if you are deciding how much operation your team should own. For a Python service, the FastAPI deployment guide covers application and deployment checks beyond this local limiter exercise.

Compute with Hivenet offers CPU instances for APIs and background services. If you choose a customer-operated instance, plan who manages Nginx, application processes, updates, TLS, and monitoring. Confirm the public connectivity requirements before committing to the deployment. The example in this article has not been deployed to a Hivenet instance.

Your next workload belongs on Hivenet.

Pick one AI, compute, or storage workload and see the difference for yourself. Spin it up in minutes, or let our team map your fastest path to production.