Next-generation Global CDN
Rate Limiting
Limit how many requests a single client can make to a site environment using the rate_limit setting in pantheon-edge.yml.
Rate Limiting limits how many requests a single client can make to a site environment in a set time window. Clients that go over the limit receive an HTTP 429 (Too Many Requests) response at the edge, so the extra requests never reach your site. Use Rate Limiting to protect your site from scrapers, aggressive bots, and traffic spikes from a single source.
Before you begin
Be sure that you have:
- A site on Next-generation Global CDN, in a workspace whose plan includes Rate Limiting.
- A local clone of your site's codebase, so you can add
pantheon-edge.yml. - An estimate of your site's peak traffic from a single client, so you can choose a tier that leaves room for real visitors.
Where to configure it
Add a rate_limit section to pantheon-edge.yml. Your workspace's plan must include Rate Limiting. For how the file works and how changes go live, see Configure features with pantheon-edge.yml.
Settings
| Setting | Required | Values | What it does |
|---|---|---|---|
criteria | ✓ | ip, ja4 | How clients are counted. ip counts each client IP address separately. ja4 counts each JA4 fingerprint separately. See Choosing between IP and JA4. |
tier | ✓ | relaxed, standard, strict, extreme, noop | Which limit applies. noop means no limit. |
penalty_seconds | ❌ | Whole seconds | How long a client stays blocked after going over the limit. If you leave it out, the default is 120 seconds (60 seconds for extreme). Set it to 0 for no lockout: the client is only refused while it is over the limit. |
fingerprint_missing_policy | ❌ | skip, fallback_ip, block | Only for criteria: ja4. What to do with a request that has no JA4 fingerprint. skip (default) doesn't rate limit it, fallback_ip counts it by IP address instead, and block refuses it. |
Tiers
| Tier | Limit | Average rate | Default penalty |
|---|---|---|---|
relaxed | 2,500 requests per 60 seconds | About 42 requests per second | 120 seconds |
standard | 500 requests per 10 seconds | 50 requests per second | 120 seconds |
strict | 1,000 requests per 10 seconds | 100 requests per second | 120 seconds |
extreme | 300 requests per 10 seconds | 30 requests per second | 60 seconds |
noop | No limit | None | None |
Examples
Limit each IP address to the standard tier:
Limit by JA4 fingerprint, count requests without a fingerprint by IP, and lock out offenders for 5 minutes:
Refuse requests only while a client is over the limit, with no lockout:
Keep the section in the file but turn rate limiting off:
What a rate-limited client sees
A request over the limit receives an HTTP 429 response with the plain-text body "Too Many Requests". The response includes a Retry-After header with the number of seconds until the client can try again, and it is never cached.
How counting works
- All of an environment's hostnames share one limit for each client. For example, requests from one IP address to
www.example.comandexample.comcount toward the same limit if both hostnames point to the same environment. - Requests are counted separately at each edge location, not across the whole network.
- The penalty is fixed. It starts when the client first goes over the limit and ends on time, even if the client keeps sending requests. If you change the tier while a client is blocked, its current penalty still runs to the end.
- If rate limiting can't be checked for a request, the request is allowed through to your site. Rate Limiting never causes a 5xx error.
Choosing between IP and JA4
- IP (
criteria: ip) counts each IP address separately. It is the simplest option, but a client that spreads requests across many IP addresses can stay under the limit. Many visitors behind the same IP address, such as an office, school, or mobile network, share one limit. - JA4 (
criteria: ja4) counts each JA4 fingerprint separately. JA4 identifies the client software making the request, based on how it sets up its secure (TLS) connection. A bot that switches IP addresses but keeps the same software keeps the same fingerprint. Real visitors using the same browser and version often share a fingerprint too, so on a busy site they count toward the same limit. Choose a tier that leaves room for your peak traffic.
Limits
- One
rate_limitrule per site environment. - Only the pre-defined tiers are available. Custom request counts and custom time windows aren't supported.
penalty_secondsmust be0or longer than the tier's window: more than 60 forrelaxed, and more than 10 forstandard,strict, andextreme.fingerprint_missing_policycan only be used withcriteria: ja4.- Rate limiting by user agent, path, or ASN isn't available.
Scope
Applies to one site environment, across all of that environment's hostnames. Each environment uses the pantheon-edge.yml in its own code.
