Rate limiting parameters
The available rate limiting rule parameters are the following:
When incoming requests match
String
- Field name in the API:
expression
(rule field). - Defines the criteria for the rate limiting rule to match a request.
- Field name in the API:
Choose action
String
- Field name in the API:
action
(rule field). - Action to perform when the rate specified in the rule is reached.
- Use one of the following values:
block
,challenge
,js_challenge
,managed_challenge
, orlog
.
- Field name in the API:
Duration
Number
- Field name in the API:
mitigation_timeout
. - Once the rate is reached, the rate limiting rule applies the rule action to further requests for the period of time defined in this field (in seconds).
- In the dashboard, select one of the available values, which vary according to your Cloudflare plan. The available API values are:
10
,60
(one minute),120
(two minutes),300
(five minutes),600
(10 minutes),3600
(one hour), or86400
(one day). - You cannot define a duration when using one of the challenge actions. In this case, when visitors pass a challenge, their corresponding request counter is set to zero. When visitors with the same values for the rule characteristics make enough requests to trigger the rate limiting rule again, they will receive a new challenge.
- When using the API, you must set the
mitigation_timeout
value to0
when the action ismanaged_challenge
,js_challenge
, orchallenge
.
- Field name in the API:
Requests
Number
- Field name in the API:
requests_per_period
. - The number of requests over the period of time that will trigger the rule.
- Field name in the API:
Period
Number
- Field name in the dashboard:
period
. - The period of time to consider (in seconds) when evaluating the request rate. The available values vary according to your Cloudflare plan.
- The available API values are:
10
,60
(one minute),120
(two minutes),300
(five minutes),600
(10 minutes), or3600
(one hour).
- Field name in the dashboard:
With the same
Array<String>
Field name in the API:
characteristics
.Set of parameters defining how Cloudflare tracks the request rate for the rule.
Use one or more of the following characteristics:
Dashboard value API value N/A (implicitly included) cf.colo.id
(mandatory)IP ip.src
IP with NAT support cf.unique_visitor_id
Header value of (enter header name) http.request.headers["<header_name>"]
Cookie value of (enter cookie name) http.request.cookies["<cookie_name>"]
Query value of (enter parameter name) http.request.uri.args["<query_param_name>"]
Host http.host
Path http.request.uri.path
AS Num ip.geoip.asnum
Country ip.geoip.country
JA3 Fingerprint cf.bot_management.ja3_hash
JSON string value of (enter key) lookup_json_string(http.request.body.raw, "<key>")
Body http.request.body.raw
Body size (select operator, enter size) http.request.body.size
Form input value of (enter field name) http.request.body.form["<input_field_name>"]
The available characteristics depend on your Cloudflare plan. Refer to Availability for more information.
You cannot use both IP with NAT support and IP as characteristics of the same rate limiting rule.
If you use
http.request.headers["<header_name>"]
in an API request, you must enter the header name in lower case, since Cloudflare normalizes header names on the Cloudflare global network.If you use Cookie value of, refer to Recommendations for additional validations you should implement.
You should not use Header value of or Cookie value of as the only characteristic of a rate limiting rule. Refer to Recommendations for details.
For more information on the
lookup_json_string
function, refer to Functions in the Ruleset Engine documentation.You should not use the
cf.colo.id
characteristic (data center ID) as a field in rule expressions. Additionally,cf.colo.id
values may change without warning. For more information about this rate limiting characteristic, refer to Determining the rate.Cloudflare will consider entire
/64
prefixes as the same IPv6 source address for the purpose of tracking the request rate.
Increment counter when
String
- Field name in the API:
counting_expression
(optional). - Only available in the Cloudflare dashboard when you enable Use custom counting expression.
- Defines the criteria used for determining the request rate. By default, the counting expression is the same as the rule expression. This default is also applied when you set this field to an empty string (
""
). - The counting expression does not extend the rule matching expression defined in If incoming requests match. Therefore, you may wish to include the matching expression in the counting expression. For example, you might want to perform rate limiting for clients sending more than five requests to
/api/
resulting in a403
HTTP status code from the origin server. In this case, the matching expression would bestarts_with(http.request.uri.path, "/api/")
and the counting expression would behttp.response.code eq 403 and starts_with(http.request.uri.path, "/api/")
. If the counting expression did not include the matching expression (that is, if you had set the counting expression tohttp.response.code eq 403
), any response with a403
status code on any URL would increase the counter. - The counting expression can include HTTP response fields. When there are response fields in the counting expression, the counting will happen after the response is sent.
- In some cases, you cannot include HTTP response fields in the counting expression due to configuration restrictions. Refer to Configuration restrictions for details.
- Field name in the API:
Also apply rate limiting to cached assets
Boolean
- Field name in the API:
requests_to_origin
(optional, with the opposite meaning of the Cloudflare dashboard option). - If this parameter is disabled (or when the
requests_to_origin
API field is set totrue
), only the requests going to the origin (that is, requests that are not cached) will be considered when determining the request rate. - In some cases, you cannot disable the Also apply rate limiting to cached assets parameter due to configuration restrictions. Refer to Configuration restrictions for details.
- Field name in the API:
With response type
String
- Field name in the API:
response
>content_type
(optional). - Only available when the rule action is Block.
- Allows you to define the content type of a custom response when blocking a request due to rate limiting.
- Available API values:
application/json
,text/html
,text/xml
, ortext/plain
.
- Field name in the API:
With response code
Integer
- Field name in the API:
response
>status_code
(optional). - Only available when the rule action is Block.
- Allows you to define the HTTP status code returned to the visitor when blocking the request due to rate limiting.
- You must enter a value between
400
and499
. The default value is429
(Too many requests
).
- Field name in the API:
Response body
String
- Field name in the API:
response
>content
(optional). - Only available when the rule action is Block.
- Allows you to define the body of the returned HTTP response when the request is blocked due to rate limiting.
- The maximum field size is 30 KB.
- Field name in the API:
Configuration restrictions
If the rule expression includes IP Lists, you must enable the Also apply rate limiting to cached assets parameter.
The rule counting expression, defined in the Increment counter when parameter, cannot include both HTTP response fields and IP Lists. If you use IP Lists, you must enable the Also apply rate limiting to cached assets parameter.
Recommendations
If you use Cookie value of as a rate limiting rule characteristic, follow these recommendations:
- Create a custom rule that blocks requests with more than one value for the cookie.
- Validate the cookie value at the origin before performing any demanding server operations.
Do not use Header value of or Cookie value of as the only characteristic of a rate limiting rule, since in some occasions these characteristics have no value. In this case, the requests would fit in the same rate limiting counter, which could unexpectedly trigger the rule for many visitors.
To prevent this situation, Cloudflare recommends that you use a second characteristic in your rate limiting rule that always has a defined value, such as IP or AS Num.