---
title: ThrottlingFilter
description: Limits the rate that requests pass through a filter. The maximum number of requests that a client is allowed to make in a defined time is called the throttling rate.
component: pinggateway
version: 2026
page_id: pinggateway:reference:ThrottlingFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/ThrottlingFilter.html
revdate: 2025-10-15T18:45:22Z
section_ids:
  ThrottlingFilter-usage: Usage
  ThrottlingFilter-properties: Properties
  ThrottlingFilter-examples: Examples
  ThrottlingFilter-moreinfo: More information
---

# ThrottlingFilter

Limits the rate that requests pass through a filter. The maximum number of requests that a client is allowed to make in a defined time is called the *throttling rate*.

When the throttling rate is reached, PingGateway issues an HTTP status code 429 `Too Many Requests` and a `Retry-After` header, whose value is rounded up to the number of seconds to wait before trying the request again.

```http
GET https://ig.example.com:8443/home/throttle-scriptable HTTP/1.1
…​
HTTP/1.1 429 Too Many Requests
Retry-After: 10
```

## Usage

```json
{
    "name": string,
    "type": "ThrottlingFilter",
    "config": {
        "requestGroupingPolicy": runtime expression<string>,
        "throttlingRatePolicy": ThrottlingPolicy reference,  //Use either "throttlingRatePolicy"
        "rate": {                                            //or "rate", but not both.
            "numberOfRequests": configuration expression<number>,
            "duration": configuration expression<duration>
        },
        "cleaningInterval": configuration expression<duration>,
        "executor": ScheduledExecutorService reference
    }
}
```

## Properties

* `"requestGroupingPolicy"`: *runtime expression<[string](preface.html#definition-string)>, optional*

  An expression to identify the partition to use for the request. In many cases the partition identifies an individual client that sends requests, but it can also identify a group that sends requests. The expression can evaluate to the client IP address or user ID, or an OpenID Connect subject/issuer.

  The value for this expression must not be null.

  Default: Empty string; all requests share the same partition

  Learn more in [PingGateway expressions](Expressions.html).

* `"throttlingRatePolicy"`: *ThrottlingPolicy [reference](preface.html#definition-reference), required if `rate` isn't used*

  A reference to, or inline declaration of, a policy to apply for throttling rate. The following policies can be used:

  * [MappedThrottlingPolicy](MappedThrottlingPolicy.html)

  * [ScriptableThrottlingPolicy](ScriptableThrottlingPolicy.html)

  * [DefaultRateThrottlingPolicy](DefaultRateThrottlingPolicy.html)

  This value for this parameter must not be null.

* `"rate"`: *[object](preface.html#definition-object), required if `throttlingRatePolicy` isn't used*

  The throttling rate to apply to requests. The rate is calculated as the number of requests divided by the duration:

- `"numberOfRequests"`: *configuration expression\<integer>, required*

  The number of requests allowed through the filter in the time specified by `"duration"`.

* `"duration"`: *configuration expression<[duration](preface.html#definition-duration)>, required*

  A time interval during which the number of requests passing through the filter is counted.

- `"cleaningInterval"`: *configuration expression<[duration](preface.html#definition-duration)>, optional*

  The time to wait before cleaning outdated partitions. The value must be more than zero but not more than one day.

- `"executor"`: *ScheduledExecutorService [reference](preface.html#definition-reference), optional*

  An executor service to schedule the execution of tasks, such as the clean up of partitions that are no longer used.

  Default: `ScheduledExecutorService`

  Learn more in [ScheduledExecutorService](ScheduledExecutorService.html).

## Examples

* [Example of a mapped throttling policy](MappedThrottlingPolicy.html#example-throttling-mapped)

* [Example of a scriptable throttling policy](ScriptableThrottlingPolicy.html#example-throttling-scriptable)

The following route defines a throttling rate of 6 requests/10 seconds to requests.

Learn how to set up and test this example in [Configure simple throttling](../gateway-guide/throttling.html#throttling-simple).

```json
{
  "name": "00-throttle-simple",
  "baseURI": "https://app.example.com:8444",
  "condition": "${find(request.uri.path, '^/home/throttle-simple')}",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "ThrottlingFilter",
          "name": "ThrottlingFilter-1",
          "config": {
            "requestGroupingPolicy": "",
            "rate": {
              "numberOfRequests": 6,
              "duration": "10 s"
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}
```

Source: [00-throttle-simple.json](../_attachments/config/routes/00-throttle-simple.json)

## More information

[org.forgerock.openig.filter.throttling.ThrottlingFilterHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/throttling/ThrottlingFilterHeaplet.html)