Cloudflare Rate Limiting

Key Articles

  1. How do I use the UI?
  2. How is Rate Limiting reported in ELS (Enterprise Log Share)?
  3. What are common issues when creating rules via the API??

Table of Contents

  1. What is Cloudflare Rate Limiting?
  2. How do I add a rule?
  3. When should I use Rate Limiting?
  4. What happens when a rule activates?
  5. How will I be charged?
  6. What are the components of a Rate Limiting rule?
  7. What thresholds should I use?
  8. How can I see how rules have been applied?

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, with up to 100 rules total.

Rate Limiting is available on all plans.

Currently, the rate limiting product is only available via API which will be documented on api.cloudflare.com.

How do I add a rule?

Rules can either be added via our UI under or via the API at api.cloudflare.com.

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.

When should I use Rate Limiting?

Common uses for Rate Limiting are:

  1. 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).
  2. to protect login forms from brute-force password-guessing attacks.
  3. 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 or 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.com/example.html to match example.html on example.com or any subdomain of example.com, or * to match any page on your site.

    One important caveat to note: pattern matching does take trailing / characters into account, i.e. a request for example.com/path is 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.com will match requests for "GET /"

    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 _ALL_.
  • the request method (e.g. POST or GET). If none is specified, all methods are matched, and the rule will list _ALL_.
  • (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. Options for periods via the UI are:
    • 1 second (default): all plans
    • 5 seconds: Enterprise only
    • 10 seconds: Enterprise only
    • 30 seconds: all plans
    • 1 minute: all plans
    • 5 minutes: Enterprise only
    • 10 minutes: Enterprise only
    • 1 hour: Enterprise only

Rule mitigations consist of:

  • a mitigation action. The options are Simulate (rule takes no action but does add data to log share data for Enterprise customers) and Ban (blocks clients that trigger the rule). There is no option to challenge a request with a CAPTCHA or Javascript-based challenge.
  • 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 options in the UI are:
    • 10 seconds: all plans
    • 30 seconds: all plans
    • 1 minute all plans
    • 5 minutes: Enterprise only
    • 10 minutes: Enterprise only
    • 30 minutes: Enterprise only
    • 60 minutes: all plans
    • 6 hours: Enterprise only
    • 12 hours: Enterprise only
    • 24 hours: Enterprise only

  • Customizing the Error Page
    • If you don't specify a custom error page, rate limiting visitors will get a default HTML page
    • You can also specify content-types: text/plain and application/json (currently not enabled but will soon)
    • (optionally, on paid plans) a custom response to rate-limited clients, at most 32kB, in text, HTML via the Customize App

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?

Aggregate data about rate limiting can be seen in Analytics. For Enterprise customers, data on individual requests is available in ELS data.

Self-service customers will not see specific clients/requests that are limited, only the aggregate data in Analytics.

Still not finding what you need?

The CloudFlare team is here to help. 95% of questions can be answered using the search tool, but if you can’t find what you need, submit a support request.

Powered by Zendesk