Skip to main content

Rate Limit

Overview

The Rate Limit policy action allows you to configure thresholds that restrict the throughput of traffic that successfully reaches your endpoint. Traffic may be limited overall or by attributes of the incoming requests.

Example

Traffic Policy rate limit based on incoming Host.

# snippet
---
actions:
- type: "rate-limit"
config:
name: "Only allow 30 requests per minute"
algorithm: "sliding_window"
capacity: 30
rate: "60s"
bucket_key:
- "req.headers['host']"

Request:

curl https://example.ngrok.app/api/v1

Result: (when limiting)

< HTTP/2 429
< retry-after: 86

Behavior

When this action is executed, information from the incoming HTTP request is used to determine which rate limit bucket the request falls into. If that bucket has received more events than its capacity over the specified duration, the request is rejected with an HTTP 429 — Too Many Requests status code. The retry-after header is set to a value in seconds after which the request may be retried. Otherwise, the request proceeds to the next action in your policy configuration.

Currently, the capacity for each bucket is applied per ingress server.

Reference

Supported Directions

  • Inbound

Configuration

Type
rate-limit
Parameter Description
namestringA name for this rate limit configuration.
algorithmstringThe rate limit algorithm to be used. Supported options: "sliding_window"
capacityuintThe maximum number of requests allowed to reach your upstream server. The minimum capacity is 1 and the maximum capacity is 2,000,000,000.
ratestringThe duration in which events may be limited based on the current capacity. This must be specified as a time duration that is a multiple of ten seconds (e.g. "90s", "10m"). The minimum value is "60s" and the maximum value is "24h".
bucket_keySet<string>The elements of this collection define the unique key of a request to collect and track the rate at which the capacity is being met. Possible values are "req.host", which is the Host, "conn.client_ip", and "req.headers['x-example-header-name']" or the related macro getReqHeader('X-Example-Header-Name'), which is the value for the specified header key, if it exists. Up to ten bucket keys can be specified.

Action Result Variables

The following variables are available following the invocation of this action.

NameTypeDescription
actions.ngrok.rate_limit.bucket_keystringThe key used for bucketing requests.
actions.ngrok.rate_limit.limitedbooleanTrue if the request was limited.
actions.ngrok.rate_limit.error.codestringCode for an error that occurred during the invocation of an action.
actions.ngrok.rate_limit.error.messagestringMessage for an error that occurred during the invocation of an action.