Configuration: rate limiting

This page documents the rate_limit directive for configuring token bucket-based rate limiting for HTTP requests. When a client exceeds the configured rate, the server returns a 429 Too Many Requests response with a Retry-After header.

rate_limit

example.com {
    rate_limit {
        rate 100
        burst 50
        key remote_address
        deny_status 429
        bucket_ttl 600
        max_buckets 100000
    }

    location /api {
        rate_limit {
            rate 10
            burst 5
            key remote_address
        }
    }
}

Multiple rate_limit blocks can be defined to apply different rules simultaneously (e.g. one per IP and one per API key).

Key types

The key directive determines what each bucket is keyed on:

Behavior

Token bucket algorithm

Each key gets its own token bucket:

• Capacity = rate + burst tokens (bucket starts full)
• Refill rate = rate tokens per second (refilled lazily on each request)
• Consumption = 1 token per request

When the bucket is empty, the request is rejected with the configured deny_status and a Retry-After header indicating how many seconds to wait.

Bucket eviction

To prevent unbounded memory growth from one-shot clients, buckets are evicted after bucket_ttl seconds of inactivity. The max_buckets setting provides a hard upper limit — when reached, new requests are rejected until stale buckets are evicted.

Per-location limits

rate_limit blocks inside location blocks apply only to requests matching that path. Both host-level and location-level rules are evaluated — a request must pass all rules to be served.

Rate limit zones

By default, each host gets its own isolated set of rate limit buckets. Rate limit zones allow multiple hostnames to share the same buckets, or to explicitly opt out of a global zone.

Zone resolution order:

1. If the host-level rate_limit block contains zone "name", the host joins the named zone.
2. If the host has its own rate_limit block (without zone) and a global zone exists, the host gets its own per-host zone (opting out of the global zone).
3. If a global rate_limit block exists without zone blocks, all hosts without explicit zones share the global zone.
4. Otherwise, each host gets its own per-host zone.

Global zone:

{
    rate_limit {
        rate 10
        burst 5
        key remote_address
    }
}

example.com {
    rate_limit {
        rate 10
        burst 5
        key remote_address
    }
}

api.example.com {
    rate_limit {
        rate 50
        burst 10
        key remote_address
    }
}

Both example.com and api.example.com share the same global zone. Their rate limit buckets are keyed by IP, so a client hitting both hosts shares the same token pool.

Named zones:

{
    rate_limit {
        zone "api"
    }
}

api.example.com {
    rate_limit {
        zone "api"
        rate 50
        burst 10
        key remote_address
    }
}

api-v2.example.com {
    rate_limit {
        zone "api"
        rate 50
        burst 10
        key remote_address
    }
}

Both api.example.com and api-v2.example.com share the named zone "api". Their rate limit buckets are shared.

Opting out of the global zone:

{
    rate_limit {
        rate 10
        burst 5
        key remote_address
    }
}

example.com {
    # Inherits global zone
}

internal.example.com {
    rate_limit {
        rate 100
        burst 20
        key remote_address
    }
    # Has its own rate_limit block → per-host zone (opts out of global)
}

Configuration reload

Rate limit buckets are stored in memory and are not preserved across configuration reloads. A reload creates fresh buckets with the new configuration.

Examples

Basic IP-based rate limiting

example.com {
    rate_limit {
        rate 10
        burst 5
        key remote_address
    }
}

Allows 15 requests burst, then 10/second sustained per IP.

API key rate limiting

api.example.com {
    rate_limit {
        rate 50
        burst 100
        key request.header.X-Api-Key
    }
}

Each unique API key gets 150 requests burst, then 50/second.

Strict endpoint with custom status

example.com {
    location /login {
        rate_limit {
            rate 2
            burst 1
            deny_status 429
        }
    }
}

Limits login to 3 requests burst, then 2/second. Returns 429 when exceeded.

Observability

Metrics

The rate limiting module emits the following metrics:

The ferron.ratelimit.zone attribute identifies which rate limit zone the request belongs to. It is set to "global" for the shared global zone, the zone name for named zones, or the hostname for per-host zones.

Logs

• DEBUG: logged when a rate limit bucket is exhausted for a key.
• WARN: logged when the registry reaches max_buckets capacity and backpressure is applied.

Structured logs

Access log fields

The rate limiting module contributes the following fields to the HTTP access log line:

Trace spans

The rate limit stage sets the following attributes on its ferron.stage.rate_limit span: