Limit Request Rate

Request rate limiting uses the leaky bucket algorithm to control the request processing rate. Requests below the throttle threshold are processed normally. Requests in the throttling range are delayed. Once the rejection threshold is reached, the system performs the configured reject action.

# Use Cases

• Smooth traffic bursts so that a sudden increase in requests does not overwhelm upstream services.
• Limit sustained high-frequency access from crawlers, API polling, or batch queries.
• Protect expensive endpoints separately by client, URI, or business identifier.

To limit the total number of requests in a fixed time window without delaying intermediate traffic, use request count limiting.

# How It Works

OpenResty Edge groups requests by one or more keys and calculates the request rate separately for each group. The leaky bucket algorithm delays burst requests in the throttling range to smooth the output rate. Requests that reach the rejection threshold trigger the reject action.

# Configuration

In the page rules for the target application, select CC Attack Protection Actions > Limit Request Rate.

# Parameters

1. Key: Groups requests so that their rates are calculated separately. The client IP address is used by default, but you can combine it with keys such as the URI or URI argument. When selecting a URI argument or Cookie, you must also specify the corresponding argument or Cookie name. See Keys.
2. Throttle At: Requests below this rate are not limited. Requests that reach this rate but have not reached the rejection threshold are delayed.
3. Reject At: Once the request rate reaches this value, the system performs the reject action.
4. Reject Action: The action performed when the rejection condition is reached. See Reject Actions.

The throttle and rejection thresholds can be specified in requests per second or requests per minute. Setting the two thresholds to the same value removes the throttling range, so the reject action is performed as soon as that rate is reached.

# Keys

Available keys include:

• Client IP Address: For example, 1.1.1.1.
• URI: For example, /openresty.
• URI Query Argument: For example, arg1 in /openresty?arg1=val1.
• Request Cookie: For example, c1 in Cookie: c1=v1.
• First IP Address in X-Forwarded-For: For example, 1.1.1.1 in X-Forwarded-For: 1.1.1.1, 1.1.1.2.
• Last IP Address in X-Forwarded-For: For example, 1.1.1.2 in X-Forwarded-For: 1.1.1.1, 1.1.1.2.
• Specified HTTP Request Header: For example, Host.
• Encrypted Cookie: Distinguishes clients by the encrypted Cookie generated by OpenResty Edge. If a request does not carry an encrypted Cookie, the system must fall back to other keys. Therefore, an encrypted Cookie must be combined with another key.

Before using X-Forwarded-For, make sure that a trusted proxy maintains the header and that clients cannot forge it.

# Reject Actions

When the rejection condition is reached, the system can perform the following preset actions. The default is Return Error Page.

• Close Request Connection: Immediately terminates the client connection without responding to the request.
• Return Error Page: Returns an error page with status code 503 by default.
• Complete hCaptcha Verification: Requires the client to pass an hCaptcha challenge.
• Complete OpenResty Edge Captcha Verification: Uses the OpenResty Edge captcha system to verify the user.
• Redirect Verification: Redirects the request to a verification page. Access can continue only after verification succeeds.
• JavaScript Challenge: Requires the client browser to run JavaScript to distinguish browsers from simple automated programs.
• Mark as Rejected: Marks the request as rejected and continues processing subsequent page rules. This action was first introduced in 24.9.1-7.
• Block IP Address: Drops all packets from the source IP at the operating system level. This action was first introduced in 26.3.1-1.

# Configuration Examples

# Limit Requests from a Specific Region

By default, this action applies to all requests and calculates the rate by client IP address. Page rule conditions can narrow its scope. For example, set the client country to JP to apply the action only to requests from Japan. See client-country for supported geographic codes.

After configuring the action and conditions, create the rule and publish the application configuration.

# Distinguish Clients with an Encrypted Cookie

An encrypted Cookie must be combined with another key. The following configuration selects both Client IP Address and Encrypted Cookie, and sets the throttle and rejection thresholds to one request per minute.

Save and publish the configuration:

On the first test request, the request does not yet carry an encrypted Cookie, so the response sets _oredge_rl through the Set-Cookie header:

$ curl localhost -H 'Host: test.com' -I
HTTP/1.1 404 Not Found
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: _oredge_rl=G63GyXMjH89ClH7dgJgSAo+f7FbPVTD5KAdkLbnkjhw=; Path=/; Secure
Req-ID: 0000008000045ed343300002

The first request carrying this Cookie has not yet reached the limit for the encrypted Cookie:

$ curl localhost -H 'Host: test.com' -I \
    -H 'Cookie: _oredge_rl=G63GyXMjH89ClH7dgJgSAo+f7FbPVTD5KAdkLbnkjhw='
HTTP/1.1 404 Not Found
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Req-ID: 0000008000045ed343300003

Sending another request with the same Cookie within the same minute triggers the limit and returns 503:

$ curl localhost -H 'Host: test.com' -I \
    -H 'Cookie: _oredge_rl=G63GyXMjH89ClH7dgJgSAo+f7FbPVTD5KAdkLbnkjhw='
HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Req-ID: 0000008000045ed343a80004

# Considerations

• Set thresholds above normal peak traffic and tune them gradually using monitoring data. A threshold that is too low can delay or reject legitimate bursts.
• Combining keys changes the counting granularity. Using only the URI makes all clients share one rate allowance. Using Client IP Address + URI calculates a separate rate for each client’s access to each URI.
• When only the client IP address is used, users behind the same NAT or proxy share an allowance.
• When validating the configuration, test behavior below the throttle threshold, within the throttling range, at the rejection threshold, and after the request rate returns to normal.