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.

YAML

# 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']"

JSON

// 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
name	string	A name for this rate limit configuration.
algorithm	string	The rate limit algorithm to be used. Supported options: "sliding_window"
capacity	uint	The maximum number of requests allowed to reach your upstream server. The minimum capacity is 1 and the maximum capacity is 2,000,000,000.
rate	string	The 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_key	Set<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.

Name	Type	Description
actions.ngrok.rate_limit.bucket_key	string	The key used for bucketing requests.
actions.ngrok.rate_limit.limited	boolean	True if the request was limited.
actions.ngrok.rate_limit.error.code	string	Code for an error that occurred during the invocation of an action.
actions.ngrok.rate_limit.error.message	string	Message for an error that occurred during the invocation of an action.