> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Rate Limit Action
> Limit the rate of traffic that successfully reaches your endpoint.
export const ConfigChildren = ({children}) => {
return
{children}
;
};
export const ConfigField = ({title, type, cel = false, defaultValue = false, required = false, children}) => {
const id = `config-${title.replace(/\.|\s|\*/g, "_")}`;
return
{title}
{type &&
{type}
}
{defaultValue &&
default:
{defaultValue}
}
{required &&
Required
}
{cel &&
Supports CEL
}
{children}
;
};
The **Rate Limit** Traffic Policy action enables 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.
## Configuration reference
The [Traffic Policy](/traffic-policy/) configuration
reference for this action.
### Supported phases
`on_http_request`
### Type
`rate-limit`
### Configuration fields
A name for this rate limit configuration. Must be less than 1024 characters.
Controls whether the rate limit is actively applied at runtime. When enabled, requests exceeding the limit are blocked or throttled as configured. When disabled, the system evaluates the rate limit but does not enforce it, allowing you to test configurations, gather metrics, or return a custom response.
The default value is true.
The rate limit algorithm to be used.
`sliding_window`
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.
The duration in which events may be limited based on the current capacity. Must be specified as a time duration that is a multiple of ten seconds (for example, "90s", "10m").
The minimum value is "60s" and the maximum value is "24h".
The elements of this collection define the unique key of a request to track the rate at which the capacity is being met.
Each bucket key is a CEL expression which includes all valid Traffic Policy [variables](/traffic-policy/variables/) and [macros](/traffic-policy/macros/).
`req.host` - The Host of the request.
`conn.client_ip` - The client IP address.
`getReqHeader('X-Example-Header-Name')` - The value for the specified header key, if it exists.
Up to ten bucket keys can be specified. For multiple buckets, the action will rate limit by each unique combination of buckets.
## Behavior
### Determining the rate limit bucket
When this action is executed, information from the incoming HTTP request is
used to determine which rate limit bucket the request falls into. Each bucket
is defined by specific criteria through the `bucket_key` configuration field
such as client IP, request host, or a header value.
If the bucket has not exceeded its capacity, the request proceeds to the next
action in your policy configuration.
## Multiple buckets
If multiple `bucket_key` values are specified, the action will create a
unique rate limit bucket for each combination of the specified keys. For
example, if you have two `bucket_key` values, such as `req.host` and `conn.client_ip`,
all incoming requests that have the exact same combination of `Host` header and client IP
will be grouped into the same rate limit bucket. To rate limit separately with two different
buckets, you can create multiple `rate-limit` actions instead.
### Rate limit exceeded
If the identified bucket has received more events than its capacity over the
specified duration:
1. The request is rejected with an `HTTP 429—Too Many Requests` status code.
2. The `retry-after` header is included in the response, indicating the number
of seconds after which the request may be retried.
### Capacity per ingress server
Currently, the `capacity` for each rate limit bucket is applied per ingress
server. This means that each server independently tracks the number of requests
and enforces the rate limits accordingly.
### Non-terminating action
This is a **Non-terminating action**. It does not return a response, and will allow Traffic Policy processing to continue to the next Action in the chain. All **Cloud Endpoint** Traffic Policies must end with a terminating action. This requirement does not apply to **Agent Endpoints**.
## Examples
### Rate limit by host header
The following [Traffic Policy](/traffic-policy/)
configuration demonstrates how to use the `rate-limit` action to rate limit
all incoming requests by the `Host` header.
#### Example Traffic Policy document
```yaml policy.yml {10} theme={null}
on_http_request:
- actions:
- type: rate-limit
config:
name: Only allow 30 requests per minute
algorithm: sliding_window
capacity: 30
rate: 60s
bucket_key:
- 'hasReqHeader(''host'') ? getReqHeader(''host'')[0] : ''unknown'''
```
```json policy.json {13} theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "rate-limit",
"config": {
"name": "Only allow 30 requests per minute",
"algorithm": "sliding_window",
"capacity": 30,
"rate": "60s",
"bucket_key": [
"hasReqHeader('host') ? getReqHeader('host')[0] : 'unknown'"
]
}
}
]
}
]
}
```
For this example, assume that ngrok is pointing at the upstream service
[https://httpbin.org](https://httpbin.org).
#### Example request
```bash theme={null}
$ curl https://httpbin.ngrok.app/get
```
```http theme={null}
HTTP/2 429
retry-after: 24
```
In this example, a connection attempt to `httpbin.ngrok.app` using the `curl`
command returns a `429` status code with a `retry-after` header indicating
the number of seconds to wait before retrying the request.
## Action result variables
The following variables are made available for use in subsequent expressions and
CEL interpolations after the action has run. Variable values will only apply
to the last action execution, results are not concatenated.
The key used for bucketing requests. This is the key used to group and track requests in the rate-limiting process, ensuring that the same bucket is subject to the rate limit across multiple requests.
Indicates whether the request was limited by the rate limit. If `true`, the request was rate-limited based on the configured limits for the specified bucket.
A machine-readable code describing an error that occurred during the action's execution.
A human-readable message providing details about an error that occurred during the action's execution.