Skip to content
WAF
Visit WAF on GitHub
Set theme to dark (⇧+D)

Rate limiting parameters

The available Rate Limiting rule parameters are the following:

  • expression String

    • Field name in the dashboard: If incoming requests match (use the Rule Builder or the Expression Editor).
    • Expression you are matching traffic on.
  • action String

    • Field name in the dashboard: Choose action.
    • Action to perform when the request rate specified in the rule is reached.
    • Use one of the following values: block, challenge, js_challenge, managed_challenge, or log.
  • characteristics Array<String>

    • Field name in the dashboard: With the same.

    • Set of parameters defining how Cloudflare tracks the request rate for the rule.

    • Use one or more of the following characteristics:

      API valueUI value
      cf.colo.id (mandatory)N/A (implicitly included)
      cf.unique_visitor_idIP with NAT support
      ip.srcIP
      ip.geoip.countryCountry
      ip.geoip.asnumAS Num
      http.request.headers["<header_name>"]Headers
      http.request.cookies["<cookie_name>"]Cookie
      http.request.uri.args["<query_param_name>"]Query
    • You cannot use both cf.unique_visitor_id and ip.src as characteristics of the same Rate Limiting rule.

    • If you use http.request.headers["<header_name>"], you must enter the header name in lower case, since Cloudflare normalizes header names at the edge.

    • If you use http.request.cookies["<cookie_name>"], refer to Recommendations for additional validations you should implement.

    • You should not use http.request.headers["<header_name>"] or http.request.cookies["<cookie_name>"] as the only characteristic of a Rate Limiting rule. Refer to Recommendations for details.

  • period Number

    • Field name in the dashboard: Period.
    • The period of time to consider (in seconds) when evaluating the request rate.
    • Use one of the following values: 10, 60 (one minute), 120 (two minutes), 300 (five minutes), 600 (ten minutes), or 3600 (one hour).
  • requests_per_period Number

    • Field name in the dashboard: Requests.
    • The number of requests over the period of time that will trigger the rule.
  • mitigation_timeout Number

    • Field name in the dashboard: Duration.
    • Once the request rate is reached, the Rate Limiting rule blocks further requests for the period of time defined in this field (in seconds).
    • Use one of the following values: 30, 60 (one minute), 600 (ten minutes), 3600 (one hour), or 86400 (one day).
    • The value must be 0 when action is challenge, js_challenge, or managed_challenge.
  • mitigation_expression String optional

    • Field name in the dashboard: N/A (currently only available via API).
    • Scope of the mitigation action.
    • Allows you to specify an action scope different from the rule scope. For example, you can count login attempts at the /login URI path using the expression field and then perform rate limiting on the entire site using the mitigation_expression field.
    • The default value is "" (empty string). When set to the default value, Cloudflare uses the value of the expression field as the mitigation expression.
    • The value must be the same as the expression value or "" when action is challenge, js_challenge, or managed_challenge.

Recommendations

  • If you use http.request.cookies["<cookie_name>"] as a Rate Limiting rule characteristic, follow these recommendations:

    • Create a Custom Firewall 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 http.request.headers["<header_name>"] or http.request.cookies["<cookie_name>"] 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.src or ip.geoip.asnum.