search close

Rate Limit Rules

access_time Updated Sep 26, 2021

Note: Rate limit rules are only included with the Premier platform. They are not included as part of our Professional platform.

Rate limit rules require agent version 3.12 or above.

Rate limit rules allow you to define arbitrary conditions (e.g., IP is 198.51.100.50, method is POST, and path is /login) and automatically begin to block or tag requests that pass a user-defined threshold (e.g., 100 requests in 1 minute).

Glossary

Term Definition
Client The source from where requests originate
Client Identifier The parts(s) of requests used to identify an individual client
Threshold How many requests must be detected before a client is rate limited
Interval The period of time requests must be detected during to pass the threshold
Counting signal The signal that needs to cross the threshold for a client to be rate limited
Action signal The signal that is logged or blocked when a client is rate limited. May be the same or different from the counting signal.
Action Whether requests are logged or blocked
Duration How long a client remains rate limited

How rate limit rules work

  1. Requests matching the conditions of the rate limit rule are tagged with the counting signal as a timeseries only signal. These requests are visible on the requests page of the console if they have also been tagged with other signals.
  2. Requests tagged with the counting signal by the rate limit rule are tallied and counted towards the threshold of the rule.
  3. When enough requests with counting signals from a given client are detected and the threshold of a rate limit rule is crossed, the client is rate limited.
  4. Subsequent requests originating from the rate limited client matching the conditions of the rate limit rule are still tagged with the counting signal.
  5. Subsequent requests originating from the rate limited client that have been tagged with the action signal are tagged with the Rate Limit signal.
    • If the action is set to “block”, the requests are blocked and tagged with the Blocked Request signal.
    • If the action is set to “log”, the requests are not blocked and no additional signals are added.

Example rate limit rules

The following example rules demonstrate how to use rate limiting for a couple of common use-cases, illustrating why you may configure your rate limit rules in certain ways. Be aware that the values such as paths and response codes used in these examples may not be the same as those used by your particular application.

Rate limit comment submissions

Rate limit rules can use the same signal for both the counting signal and the action signal. This example rule demonstrates how to rate limit users' ability to submit comments.

This rule looks for POST requests to the /comments.php file and tags them with the Comment Submission custom signal as the counting signal. Because the user may attempt to change their IP address to circumvent the rate limit, the rule uses both the IP address and the value of the User-Agent request header as the client identifiers to track requests from this user.

When 10 requests (the threshold) tagged with the Comment Submission signal (the action signal) are detected from a unique IP address and User-Agent within 1 minute (the interval), any subsequent requests with the Comment Submission signal from that IP address and User-Agent will be blocked (the action) for the next 15 minutes (the duration).

Screenshot of an example rule that rate limits comment submissions, as described above.

Credit card validation attempts

This example rule demonstrates how to rate limit credit card validation attempts after too many failed attempts. This is example where the counting signal and the action signal are different.

This use-case requires two separate rules: a request rule to track credit card validation attempts and a rate limit rule to track credit card validation failures and rate limit the originating IP address.

The request rule looks for POST requests to the /checkout-payment.php file and tags them with the Credit Card Attempt custom signal.

Screenshot of an example rule that tags credit card attempt requests, as described above.

The rate limit rule looks for requests tagged with the Credit Card Attempt custom signal, as well as if the request received a 401 response code indicating the credit card validation attempt was a failure. The rule applies a Credit Card Failure custom signal (the counting signal) to these requests.

When 5 requests (the threshold) tagged with the Credit Card Failure signal are detected from a signal IP within 10 minutes (the interval), any subsequent requests tagged with the Credit Card Attempt signal (the action signal) from that IP will be blocked (the action) for the next hour (the duration).

Screenshot of an example rule that rate limits credit card validation failures, as described above.

Rate limit rule limitations

Signals shared between rate limit rules and request rules

Which requests are blocked when a client is rate limited is determined solely by whether or not the action signal is present. This means that, after a client has been rate limited, any requests tagged with that signal by request rules will also be blocked if the rate limit rule action is set to block.

Other rate limit rule limitations

  • A given signal can only be used as the counting signal for a single rate limit rule. A signal can’t be used as the counting signal in more than one rate limit rule.
  • A site can only have 1 rate limit rule using a client identifier other than IP address. For example, if you create a rate limit rule that uses a cookie value as the client identifier, all subsequent new rate limit rules on that site can only use IP address as the client identifier.

Rate limit fields

Field Type Properties
Agent name String Text or wildcard
Country Enum ISO countries
Domain String Text or wildcard
IP address IP Text or wildcard, supports CIDR notation
Method Enum GET, POST, PUT, PATCH, DELETE, HEAD, TRACE
Path String Text or wildcard
POST parameter Multiple Name (string), Value (string)
Query parameter Multiple Name (string), Value (string)
Request cookie Multiple Name (string), Value (string)
Request header Multiple Name (string), Value (string), Value (IP)
Response code String Text or wildcard
Response header Multiple Name (string), Value (string)
Scheme Enum http, https
Signal Multiple Type (signal), Parameter name (string), Parameter value (string)
User agent String Text or wildcard