Table of Contents
- What is Cloudflare Rate Limiting?
- How do I add a rule?
- When should I use Rate Limiting?
- What happens when a rule activates?
- How will I be charged?
- What are the components of a Rate Limiting rule?
- What thresholds should I use?
- How can I see how rules have been applied?
- Related Articles
What is Cloudflare Rate Limiting?
Rate Limiting is a feature that allows customers to identify and mitigate high request rates automatically, either for specific URLs or for an entire zone.
Rate Limiting is an add-on service (available in all user plans) that when enabled, appears in the Firewall app of the Cloudflare dashboard. For subscription information, visit Cloudflare Pricing.
Currently, the rate limiting product is only available via API which will be documented on api.cloudflare.com.
How do I add a rule?
If you encounter issues when creating a rule via the API, please review the common issues encountered when using the API, and if your issue is not covered, please contact Support for additional assistance.
The number of rate limiting rules are based on the plan: 1 rule for Free plans, 3 rules for Pro and Business plans and up to 100 for Enterprise plans.
When should I use Rate Limiting?
Common uses for Rate Limiting are:
- to protect your site from a layer 7 (HTTP-based) DDoS attack that is either not stopped by "I'm Under Attack" mode or in situations where using "I'm Under Attack" mode is not desired (e.g. if you have legitimate automated traffic that would be unable to pass the challenge, or you do not wish to show an interstitial challenge page to users).
- to protect login forms from brute-force password-guessing attacks.
- to limit how often a client can access a resource that has a high processing cost on your origin, e.g. forum searches, certain API calls or other database-intensive actions.
What happens when a rule activates?
Once a client (an individual IPv4 address or IPv6 /64 block) exceeds a rule threshold, its requests will matching the rule pattern no longer be sent to your origin. Clients will receive an HTTP 429 with a
Retry-After: X header to indicate how long their timeout period is/when they will be able to send requests again.
Note that the request rates are calculated locally in individual PoPs. In practice, this should not matter--all requests from a given client will route to the same PoP almost always (the PoP can change due to routing changes, but these are infrequent).
Cached resources, even if they match a rule, are never rate-limited.
How will I be charged?
Rate Limiting charges will be usage-based: once you create a rule, Cloudflare will track requests that match that rule but are not blocked and sent to your origin (unless you configure to rate limit on edge requests), and bill you at the end of your billing cycle.
There is no up-front cost to create rules. Usage-based billing is covered in detail in Billing for Cloudflare Rate Limiting.
Note: during the API-only release, there are no invoices or charges for usage. When we add the user interface in the dashboard we will start billing for rate limiting, and charges will be made at the end of each billing cycle, in arrears for the previous billing cycle.
What are the components of a Rate Limiting rule?
A Rate Limiting rule consists of a set of request matching criteria, rate matching criteria and a mitigation. Requests are matched on:
- the request path (e.g.
http://example.com/example/*). This is case insensitive and cannot match against a query string. An asterisk ("*") will match any sequence of characters, including an empty sequence. For example, you'd use
*.example.com/*to match any path on a subdomain of
*example.com/example.htmlto match example.html on example.com or any subdomain of example.com, or
*to match any page on your site.
There is one important caveat to note: pattern matching does take trailing / characters into account, i.e. a request for
example.com/pathis not the same as
example.com/path/. As such, you should create rules for both if you want to match requests for that path and do not wish to use a wildcard. The one exception is the homepage:
example.comwill match requests for "
Additionally, patterns cannot match content after query strings (?s) or anchors (#s).
- the request scheme (e.g. HTTP or HTTPS). If none is specified, both are matched, and the rule will list
- the request method (e.g. POST or GET). If none is specified, all methods are matched, and the rule will list
- (optionally) the response code returned by the origin (e.g. 401, 403). Note that if you include this and the rule triggers, subsequent requests from that client will be blocked regardless of which code would have been returned--since this cannot be determined without sending the request, we must block all requests.
Rate matching includes:
- A number of requests, at minimum 2, since 1 would match any request and should instead be handled by making the path unavailable completely (e.g. by configuring the origin to return a 403).
- A time period. Once a client exceeds the threshold above in the time period, the rule will trigger. The periods available, by plan, are:
- 1 second or 1 minute (Free and Pro)
- 1 second, 1 minute, or 10 minutes (Business)
- Any period between 1 second and 1 hour (Enterprise)
Rule mitigations consist of:
- a time out/ban period. This must be greater than the threshold, and attempting to set a timeout shorter than the threshold will result in the API automatically increasing the timeout to equal the threshold. The periods available, by plan, are:
- 1 minute or 1 hour (Free and Pro)
- 1 minute, 1 hour, or 24 hours (Business)
- Any period between 10 seconds and 24 hours (Enterprise)
- Customizing the Error Page
- If you don't specify a custom error page, rate limiting visitors will get a default HTML page
- On paid plans you can create a custom response to rate-limited clients, at most 32kB, in text, HTML via the Customize App
- On Business and Enterprise, you can also specify content-types and a response in the rule itself:
What thresholds should I use?
All zones are different, and the appropriate threshold will depend on your typical traffic profile and needs.
Generally speaking, you can calculate a rough estimate of your normal traffic volume across your entire site by dividing the uncached requests over a 24-hour period by unique visitors for the same period. Then, divide that number by the estimated average length of a visit, in minutes, to give you a rough idea of average requests per client per minute. Multiplying that value by 4 (or larger) to establish a rough per-minute threshold for your entire site. If you are unsure, using a higher value is typically fine--most attacks are an order of magnitude above typical traffic rates.
To obtain a more specific threshold, you may wish to compare request rates over multiple days, or review individual days and base thresholds off peak traffic times.
For specific URLs, you should be able to calculate a similar value by reviewing your local access logs (or your Enterprise log share if you are an Enterprise customer)/unique clients logged for that URL. If you have not done so already, you should restore original IPs in your access logs.
You should set your threshold well above this value to account for clients that send more legitimate requests than both. While valid outlying client traffic patterns will vary per site, quadruple the average request rate is probably a good baseline to defend against attacks. You can then adjust the thresholds based on user reports and your own monitoring.
If you are actively under attack and are unsure how best to mitigate it, please file a support ticket and Cloudflare staff will help you review your traffic and make recommendations on appropriate thresholds.
How can I see how rules have been applied?
Self-service customers will not see specific clients/requests that are limited, only the aggregate data in Analytics.