What Is Rate Limiting? Explained With Real nginx and Caddy Tests (2026)

What Is Rate Limiting? Explained With Real nginx and Caddy Tests (2026)

Rate limiting means a server caps how many requests a single sender may make within a given time. Anyone who goes over the cap stops getting answers and receives status code 429 Too Many Requests instead, until there is room again. It protects against bots hammering login forms, scrapers that drain a site in seconds, and the perfectly ordinary case of one broken script taking a service down for everybody else.

That is the definition every glossary gives you. This article goes further. We set up rate limiting in nginx 1.31.8 and Caddy 2.11.9 ourselves, fired 50 simultaneous requests at each and counted what got through. We also analysed this website’s access log over 13 days to answer a question tutorials almost never ask: which limit would actually have hit whom on real traffic?

Four findings up front:

1. In 13 days we received 83,377 requests from 16,338 addresses. Only 88 addresses ever sent 10 or more requests within the same second, yet they caused 27.6 % of all traffic. 72 % of their requests ended in a 404, compared with 21 % for everyone else.

2. The peak was 380 requests in one second from a single address.

3. The log contained 42 addresses claiming to be Googlebot. Only 6 were genuine (verified via reverse DNS). The real Googlebot never exceeded 3 requests per second; the fakes went up to 20.

4. One of the most common nginx configs in tutorials does nothing at all: limit_req in a block with return 200 let 218,184 out of 218,184 requests through in our test.

A glowing funnel in front of a server that only lets an even stream of particles through

What is rate limiting, exactly?

Picture a checkout that can serve at most ten customers per minute. If eleven arrive, the eleventh waits. If a hundred show up at once because a coach just pulled in, a queue forms, and at some point the manager sends some of them home. Rate limiting is the rule that decides how long the queue may get and who gets sent home.

Technically every rate limit consists of three building blocks:

  1. A key: who is being counted? Usually the IP address; for APIs often the API key or the user account; sometimes a combination of address and path.
  2. A rate: how much is allowed? For example 10 requests per second, 60 per minute or 5,000 per hour.
  3. A reaction: what happens when it is exceeded? Reject (429), delay (queue), or just log.

The difference from a firewall matters. A firewall decides by who (this address may enter, that one may not). Rate limiting decides by how much. A perfectly normal visitor can suddenly be slowed down if they behave unusually, and an attacker who moves politely slowly gets through. So one does not replace the other. How to lock down the server itself is covered in our guide UFW firewall setup.

The difference from fail2ban also matters, because the two are often confused. fail2ban reads logs after the fact and bans addresses at the firewall for a while. Rate limiting acts during the request, in the web server or the application, and answers immediately. In our article fail2ban setup we measured that fail2ban catches fast bots well but misses slow ones. Rate limiting has the same weakness, just in a different place. They complement each other.

Why do you need rate limiting?

There are four typical reasons, and they call for different limits:

Brute-force protection. A login form that allows unlimited attempts is an invitation. Limits here are strict: a few attempts per minute per address, often additionally per user account.

Protection against scraping and resource drain. A bot fetching 380 pages per second costs CPU, bandwidth and, on dynamic sites, database queries. The goal here is not to lock out every bot but to push the rate down to something bearable.

Fairness for APIs. Anyone offering an API wants to stop one customer from slowing down everyone else. That is why almost every public API has documented quotas. In What is an API? we measured how GitHub does it: 60 requests per hour unauthenticated, 5,000 with a token.

Cost control. If a paid service sits behind an endpoint (say an AI model billed per request), a rate limit is the cheapest insurance against a bill you did not expect.

What rate limiting does not do: it does not protect against a real distributed DDoS attack from tens of thousands of addresses. Each address stays under the limit and the sheer volume still arrives. Only an upstream service with large capacity helps there, usually a CDN.

The four algorithms behind rate limiting

A limit like “10 per second” sounds unambiguous, but it can be counted in at least four ways. The difference decides whether a visitor loading a page with eight images gets slowed down or not.

Fixed window

The simplest approach: there is one counter per second (or minute). On the eleventh request in that second it is over; with the next second the counter starts at zero again.

The problem is at the edges. Someone who sends 10 requests in the last 100 milliseconds of second 1 and 10 more in the first 100 milliseconds of second 2 has pushed 20 requests through in 200 milliseconds, twice the limit. For login protection that usually does not matter; for expensive endpoints it does.

Sliding window

Instead of rigid seconds, the server always looks at the last full second (or minute) measured from now. That closes the edge gap. The price: you have to remember individual request timestamps, or at least a weighting of two windows. Caddy’s rate limit module works this way.

Token bucket

Each sender has a bucket of tokens. Every request costs one token. The bucket is refilled at a fixed speed, for example 10 tokens per second, but holds only a maximum, say 20. A visitor who has been quiet for a while therefore has a full bucket and may briefly make 20 requests at once. After that it only continues at the refill rate.

That is usually what you want: allow short spikes (a page loads its images and scripts), cap sustained load. Most cloud APIs work this way.

A glass bucket full of coins being refilled drop by drop from a tap

Leaky bucket

The mirror image: requests land in a bucket with a hole in the bottom that drains at a fixed speed. If the bucket overflows, requests are rejected. What is in the bucket is processed not immediately but at the pace of the hole. That smooths traffic behind the limit perfectly but costs waiting time.

nginx works on the leaky bucket principle, and that is exactly why it behaves differently from what many people expect. We measured it.

AlgorithmAllows spikes?Edge problem?Typical in
Fixed windowYes, at window edges even doubleYesSimple middleware, Redis counters
Sliding windowLimitedNoCaddy (caddy-ratelimit), many APIs
Token bucketYes, up to bucket sizeNoCloud APIs, Envoy, Go x/time/rate
Leaky bucketOnly with a queue (burst)Nonginx limit_req

HTTP 429 and the headers that go with it

When a limit kicks in, the server should answer with 429 Too Many Requests. That is the code clients, libraries and search engines understand as “slow down, please”. Ideally it comes with a Retry-After header giving the number of seconds after which a new attempt makes sense.

Many APIs additionally send headers that reveal the current state even before the limit is reached. Common ones are X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. An IETF draft proposes standardised names (RateLimit and RateLimit-Policy), but the X- variants are still the most widespread.

One trap right away: without further configuration nginx answers with 503 Service Unavailable, not 429. To a monitoring service that looks like an outage, and Googlebot treats 503 as “page currently broken”. The line limit_req_status 429; therefore belongs in every nginx config that uses rate limiting.

Rate limiting in nginx: what really happens

For the test we started nginx 1.31.8 in a Docker container with a limit of 10 requests per second per address and compared four variants. Each variant received 50 requests at once (using xargs -P50 and curl), with a three-second pause between runs so the counter could drain.

The base configuration:

http {
    # Zone "a": 10 MB of memory, key = client IP, 10 requests per second
    limit_req_zone $binary_remote_addr zone=a:10m rate=10r/s;
    limit_req_status 429;

    server {
        listen 80;
        root /usr/share/nginx/html;

        location /strict/  { limit_req zone=a; }
        location /burst/   { limit_req zone=a burst=20; }
        location /nodelay/ { limit_req zone=a burst=20 nodelay; }
    }
}

For context: according to the nginx documentation, 10 MB of zone memory holds roughly 160,000 addresses. $binary_remote_addr is the address in compact binary form, which saves memory compared with $remote_addr.

The result

VariantLet through (200)Rejected (429)Slowest response
no limit5000.04 s
limit_req zone=a1490.004 s
burst=2021291.99 s
burst=20 nodelay21290.04 s

Three things stand out.

Without burst, nginx lets exactly one request through. Not ten, as you might expect from “10 per second”. The reason is the leaky bucket: nginx converts 10 per second into one request per 100 milliseconds. If 50 requests arrive in the same millisecond, the bucket is full after the first. For a real visitor this means a page that loads CSS, JavaScript and five images alongside the HTML would be delivered broken with this limit. An article page on getmind.io references seven such files. A site-wide limit without burst would be an own goal.

With burst=20, 21 get through, but slowly. The first one immediately, the next 20 go into a queue and are processed at the 100-millisecond pace. The last one waited almost two seconds. That smooths the load perfectly, but to a human a page whose last image hangs for two seconds feels broken.

With burst=20 nodelay, the same 21 get through, but instantly. The queue is not waited out; it is paid out immediately as an allowance. Slots still only free up at the 100-millisecond pace. For websites this is almost always the right choice: allow spikes, cap sustained load. It matches token bucket behaviour.

A second run with wrk (20 connections, 3 seconds of continuous fire) shows that the rates hold over time: without burst, exactly 31 of 162,510 requests got through, roughly 10 per second. With nodelay it was 51, the 10 per second plus the one-off buffer of 20. Without nodelay, wrk only managed 31 requests in three seconds in total, because every connection got stuck in the queue. A browser runs into exactly the same thing.

Three lanes: a hard barrier, an orderly queue and a group that passes immediately

The return trap

We first built the test differently, the way you find it in many examples:

location /api/ {
    limit_req zone=a;
    return 200 "ok\n";
}

Result: 218,184 requests in three seconds, all with 200. The limit was ignored completely. The reason: nginx processes a request in phases, and return belongs to the rewrite phase, which runs before the phase in which limit_req counts. The response is already out before the limit is consulted. This is documented behaviour, but hardly any tutorial mentions it.

In practice it bites anyone who tests rate limiting with a return “just to quickly check it works”. It then appears not to work, or worse: you test a different path that does work and assume a block with return or rewrite ... last is protected. Behind proxy_pass, fastcgi_pass or for static files, limit_req works reliably; we confirmed that with the numbers above.

A configuration for everyday use

From these measurements, a typical website with a login area ends up with this split:

http {
    # Generous for everything: pages, images, scripts
    limit_req_zone $binary_remote_addr zone=site:10m rate=20r/s;
    # Strict for login and forms: 5 per minute
    limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;

    limit_req_status 429;
    limit_req_log_level warn;

    server {
        location / {
            limit_req zone=site burst=40 nodelay;
            proxy_pass http://127.0.0.1:3000;
        }

        location = /login {
            limit_req zone=login burst=3 nodelay;
            proxy_pass http://127.0.0.1:3000;
        }
    }
}

limit_req_log_level warn makes rejections land in the log as warnings instead of errors; otherwise the error log fills up quickly during a bot rush with entries like limiting requests, excess: 1.000 by zone "a". Those exact lines can be read by fail2ban: the bundled nginx-limit-req jail bans addresses that repeatedly hit the limit at the firewall level. That turns a brake into a ban.

If you run nginx in front of an application, the basics are in nginx as a reverse proxy.

Rate limiting in Caddy

Unlike nginx, Caddy has no built-in rate limiting. There is a widely used module, though: caddy-ratelimit by Caddy author Matt Holt. You need a custom Caddy binary for it, either built with xcaddy or via the download service on caddyserver.com, where you add modules with a click. We used the latter. The result reports itself as v2.11.9 and additionally lists the module http.handlers.rate_limit.

The test configuration with the same goal, 10 requests per second per address:

{
    order rate_limit before respond
}

:18081 {
    rate_limit {
        zone per_ip {
            key    {remote_host}
            events 10
            window 1s
        }
    }
    respond "ok"
}

The line order rate_limit before respond is required because the module is not part of Caddy’s default handler order. Without it Caddy refuses to start, which, incidentally, is friendlier than nginx silently ignoring the limit.

The result

TestLet through (200)Rejected (429)
50 simultaneous1040
50 sequential, 50 ms pause each3020

Caddy behaves the way you intuitively read “10 per second”: of 50 simultaneous requests, exactly 10 get through. The sliding window has no queue and needs no burst parameter; a visitor may make their 10 requests as fast as they like. Rejected requests automatically get 429 and a Retry-After: 1 header, without any configuration.

In Caddy, then, the limit is directly the spike allowance. If you protect a website with many files per page, set events higher accordingly, say 30 to 50 per second for the whole site, plus a separate strict limit for the login path. How Caddy and nginx differ otherwise is measured in Caddy vs nginx.

What a limit would have hit on real traffic

Everything so far was lab work. The really interesting question is: where do you set the line? To answer it we analysed the Caddy access log of getmind.io over 13 days (7 to 20 November 2026) and determined, for every address, the highest number of requests within a single second.

Peak of an addressNumber of addressesShare of total traffic
2 or more per second1,90861.9 %
5 or more per second27434.6 %
10 or more per second8827.6 %
20 or more per second6626.6 %
50 or more per second3715.0 %

In total 83,377 requests from 16,338 addresses. The share refers to all requests those addresses sent over the whole period.

What the numbers show:

A limit of 2 per second would have been absurd. Almost 2,000 addresses would have hit it, including practically every normal visitor loading a page with images. That is exactly the trap people fall into when they set a rate limit without burst or with too small a window.

From 10 per second it gets clean. The 88 addresses above that are a very small group causing more than a quarter of all traffic. And that traffic is mostly junk: 72 % of their requests ended in a 404 because they were probing paths like /wp-login.php, /.env or /.git/config, which do not exist on a static Astro site. For all other addresses the 404 share was 21 %.

The peak was 380 requests in a single second. Several of the most aggressive addresses came from the data centre networks of large cloud providers and posed as browsers with a perfectly ordinary Chrome user agent.

For a static site like ours that traffic is harmless; Caddy serves it from memory. On a shop or a WordPress install, where every 404 page queries the database, 380 requests per second from one address would be real load.

A barrier holds back a swarm of red drones while a single blue search robot passes through a side lane

The fake Googlebot: why user-agent exceptions are dangerous

The first worry with rate limiting is almost always: “Will I lock out Google?” The obvious solution you often read is an exception for anything that calls itself Googlebot. Our data shows why that is a bad idea.

The log contained 1,474 requests from 42 different addresses whose user agent contained “Googlebot”. We checked every address the way Google itself recommends: reverse DNS lookup, the name must end in googlebot.com or google.com, and a forward lookup of that name must return the same address again.

AddressesRequestsHighest rate
Real Googlebot61,0183 per second
Fake Googlebot3645620 per second

Six out of 42. The large majority of “Googlebots” were fake, and the fakes were considerably more aggressive than the original. The real Googlebot never made more than three requests per second in 13 days. Google regulates its crawl rate itself and throttles on its own as soon as a server answers more slowly or responds with 429 and 503.

Two practical rules follow:

  1. No exceptions by user agent. The user agent is free text. Anyone who waves Googlebot through blanket-style waves through exactly the bots that call themselves that for this reason.
  2. Set the limit generously enough that real crawlers never reach it. With 10 or more requests per second plus a buffer, the real Googlebot at three per second is nowhere near any limit. In our data Bingbot never exceeded 3, GPTBot and ClaudeBot never exceeded 5.

If you still want an exception for search engines, it has to be by address. Google publishes the Googlebot IP ranges as a JSON file, and nginx can exempt address ranges from the limit via geo and map by setting the key to an empty value for those addresses. nginx does not count empty keys.

geo $limit_exempt {
    default        0;
    66.249.64.0/19 1;   # example: one Googlebot range, keep the list up to date
}

map $limit_exempt $limit_key {
    0 $binary_remote_addr;
    1 "";
}

limit_req_zone $limit_key zone=site:10m rate=20r/s;

Maintaining that list is work, and an outdated list is worse than none. For the vast majority of websites a sufficiently high limit is the better solution.

Rate limiting behind a CDN or reverse proxy

The most common mistake in practice has nothing to do with the algorithm and everything to do with the key. If a CDN such as Cloudflare or another reverse proxy sits in front of your server, all requests appear, from your server’s point of view, to come from a handful of proxy addresses. $binary_remote_addr is then the same value for thousands of visitors, and the limit hits everyone at once. In the worst case you lock everybody out of the whole site as soon as one bot comes along.

The fix is to take the real visitor address from the header the proxy sends, but only from addresses that really belong to the proxy:

# Only trust the header from these senders
set_real_ip_from 173.245.48.0/20;   # example: one Cloudflare range, add the complete list
real_ip_header   CF-Connecting-IP;

In Caddy, the global trusted_proxies option takes care of this. Afterwards {remote_host} holds the proxy’s address, {client_ip} the real visitor address, and the latter is what belongs in the rate limit key.

If you instead trust the X-Forwarded-For header from any sender, the limit becomes worthless: every bot can send a different invented address with every request and is never counted.

Several protective rings around a server: cloud, web server and application

Where should the rate limit live?

Rate limiting can be implemented in three places, and each has its purpose:

In the CDN or edge service. Traffic is intercepted before it even reaches your server. This is the only layer that helps against large volumes. Downside: the rules are often coarse and heavily restricted on free plans.

In the web server (nginx, Caddy). Fast, light on resources, independent of the application. Ideal for per-address protection: login paths, expensive endpoints, a general brake on scrapers. But the web server knows nothing about user accounts or API keys.

In the application. Only here can you distinguish by account, API key or plan (“free customers 100 requests per hour, paying ones 10,000”). With several servers you need a shared counter for that, usually Redis; otherwise each server counts on its own and the limit multiplies by the number of instances.

The sensible combination for a small to medium server: a generous per-address limit in the web server, a strict limit for login and forms, and fail2ban reading the rejections and banning persistent offenders at the firewall. For applications with accounts, additionally a per-account limit in the application.

Handling rate limits correctly as a client

Rate limiting has a second side: if you consume an API yourself, you will eventually run into a limit. Three rules:

  1. Do not retry immediately on 429. A script that starts the next attempt straight after a 429 only burns more quota and prolongs the block.
  2. Respect Retry-After. If the header is present, wait exactly that long.
  3. Exponential backoff with jitter. If the header is missing, wait 1 second, then 2, then 4, then 8, each with a bit of randomness so that a hundred clients do not knock again at the same moment.

A minimal example in Python:

import random, time, requests

def get_with_backoff(url, attempts=6):
    for n in range(attempts):
        r = requests.get(url, timeout=10)
        if r.status_code != 429:
            return r
        wait = float(r.headers.get("Retry-After", 2 ** n))
        time.sleep(wait + random.uniform(0, 0.5))
    raise RuntimeError("Rate limit not lifted after several attempts")

Checklist: setting up rate limiting

  • Clarify the goal: brute force, scraping, fairness or cost? That determines how high the limit should be.
  • Look at your own data: find the highest request rate per address in the access log before you pick a number.
  • nginx: always set limit_req_status 429;; for websites use burst with nodelay.
  • nginx: do not test with return; test with real files or a proxy_pass.
  • Caddy: add the caddy-ratelimit module and set order rate_limit before ....
  • Limit login and forms separately and much more strictly.
  • Behind a CDN or proxy: only take the real visitor address from trusted proxy addresses.
  • No exceptions by user agent.
  • Log rejections and ban persistent offenders with fail2ban (nginx-limit-req).
  • After setting it up, test from a second machine: do ordinary page views get through cleanly?

Conclusion

Rate limiting is one of the cheapest protective measures a server can have: a few lines of configuration, barely measurable overhead, and a small group of senders, which in our case caused more than a quarter of all traffic, gets slowed to a bearable level.

The pitfalls are not in the principle but in the details. Without burst, nginx lets only a single one of several simultaneous requests through, and without configuration it answers with 503 instead of 429. A return bypasses the limit completely, with no error message. Behind a proxy without real-IP configuration you count all visitors as one. And anyone who exempts search engines by user agent lets 36 fakes through, in our case, to protect 6 genuine crawlers that would never have reached the limit anyway.

Our recommendation to start with: 20 requests per second with a buffer of 40 for the whole site, 5 per minute for the login, plus fail2ban on the rejections. And then look at your own log.

Frequently asked questions about rate limiting

What does rate limiting mean in simple terms?

It is a cap on how many requests one sender may make to a server or API within a period of time. Go over it and the server tells you to wait, usually with HTTP status 429.

What does the error 429 Too Many Requests mean?

You have exceeded a service’s rate limit. It is not a permanent error: after a waiting period, often stated in the Retry-After header, requests work again. If you see a 429 page as a visitor, wait briefly instead of reloading repeatedly, because every reload counts too.

Is rate limiting the same as DDoS protection?

No. Rate limiting caps individual senders. A distributed attack from tens of thousands of addresses stays under any limit per address and still overloads the server. Only an upstream service with enough capacity helps there, such as a CDN with DDoS protection. Rate limiting is one building block, not complete protection.

What rate limit makes sense for a normal website?

For pages, images and scripts, a limit of about 20 requests per second per address with a buffer of 40 worked well in our tests. For login forms, far less, around 5 per minute. More important than any rule of thumb is looking at your own access log: how many requests do real visitors send at their peak?

Does rate limiting lock out Google?

Not with a sensible limit. The real Googlebot never exceeded 3 requests per second in our 13 days. It also throttles itself when it receives 429 or 503. It only becomes a problem with very low limits, or if nginx answers with 503 (because limit_req_status 429 is missing) and that happens persistently.

What is the difference between rate limiting and throttling?

The terms are often used interchangeably. When people distinguish them, it is like this: rate limiting rejects excess requests (429), throttling slows them down instead of rejecting them, for example with a queue. By that definition nginx with burst but without nodelay is throttling, and with nodelay it is rate limiting.

What is the difference between burst and nodelay in nginx?

burst defines how many requests beyond the rate are accepted. Without nodelay they are queued and processed at the rate’s pace; in our test the last one took almost two seconds. With nodelay they are served immediately, but the buffer slots still only free up at the rate’s pace.

Do I need rate limiting if I already have fail2ban?

Yes, the two complement each other. fail2ban reacts to log entries after the event and bans at the firewall; rate limiting acts immediately on every request. Best is to combine them: nginx rejects with 429, fail2ban reads those rejections via the nginx-limit-req jail and bans addresses that keep hitting the limit.

Can rate limiting be bypassed?

Yes, by an attacker spreading requests across many addresses, for instance via a botnet or rented proxies. Each address then stays under the limit. That is why good APIs also count per account or API key, and why rate limiting is always just one of several layers of protection.