---
title: CircuitBreakerFilter
description: Monitors failures. When the number of failures reaches a configured failure threshold, the circuit breaker trips, and the circuit is considered open. Calls to downstream filters are stopped, and a runtime exception is returned.
component: pinggateway
version: 2026
page_id: pinggateway:reference:CircuitBreakerFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/CircuitBreakerFilter.html
revdate: 2026-03-16T18:30:00Z
section_ids:
  CircuitBreakerFilter-usage: Usage
  CircuitBreakerFilter-properties: Properties
  CircuitBreakerFilter-example: Example
  CircuitBreakerFilter-moreinfo: More information
---

# CircuitBreakerFilter

Monitors failures. When the number of failures reaches a configured failure threshold, the circuit breaker trips, and the circuit is considered *open*. Calls to downstream filters are stopped, and a runtime exception is returned.

After a configured delay, the circuit breaker is reset, and is the circuit considered *closed*. Calls to downstream filters are restored.

## Usage

```json
{
  "name": string,
  "type": "CircuitBreakerFilter",
  "config": {
    "maxFailures":  configuration expression<integer>,
    "openDuration": configuration expression<duration>,
    "slidingCounter": object,
    "openHandler": Handler reference,
    "executor":  ScheduledExecutorService reference
  }
}
```

## Properties

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

  The maximum number of failed requests allowed in the window given by `size`, before the circuit breaker trips. The value must be greater than zero.

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

  The duration for which the circuit stays open after the circuit breaker trips. The `executor` schedules the circuit to be closed after this duration. The duration can't exceed `1 day`.

* `"slidingCounter"`: *[object](preface.html#definition-object), required*

  A sliding window error counter. The circuit breaker trips when the number of failed requests in the number of requests given by `size` reaches `maxFailures`.

  The following image illustrates how the sliding window counts failed requests:

  ![Example sliding window error counter.](_images/sliding-window.svg)

  ```json
  {
    "slidingCounter":  {
      "size": configuration expression<number>
    }
  }
  ```

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

    The size of the sliding window in which to count errors.

    The value of `size` must be greater than zero, and greater than the value of `maxFailures`, otherwise an exception is thrown.

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

  The [Handler](Handlers.html) to call when the circuit is open.

  Default: A handler that throws a RuntimeException with a "circuit-breaker open" message.

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

  A [ScheduledExecutorService](ScheduledExecutorService.html) to schedule closure of the circuit after the duration given by `openDuration`.

  Default: The default ScheduledExecutorService in the heap

## Example

In the following example, the circuit breaker opens after 11 failures in the previous 100 requests, throwing a runtime exception with a "circuit-breaker open" message. The default ScheduledExecutorService in the heap closes the circuit-breaker after 10 seconds.

```json
{
  "type": "CircuitBreakerFilter",
  "config": {
    "maxFailures": 10,
    "openDuration": "10 seconds",
    "openHandler": {
      "type": "StaticResponseHandler",
      "config": {
        "status": 500,
        "headers": {
          "Content-Type": [ "text/plain" ]
        },
        "entity": "Too many failures; circuit opened to protect downstream services."
      }
    },
    "slidingCounter": {
      "size": 100
    }
  }
}
```

## More information

[org.forgerock.openig.filter.circuitbreaker.CircuitBreakerFilter](../_attachments/apidocs/org/forgerock/openig/filter/circuitbreaker/CircuitBreakerFilter.html)