> ## 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.
# Circuit Breaker Action
> Prevent overload and maintain system reliability by rejecting requests when errors and volume exceed set thresholds.
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 Circuit Breaker Traffic Policy action helps you maintain system reliability
by rejecting requests when the error rate and request volume within a rolling
window exceed defined thresholds. It pauses traffic temporarily to allow the
system to recover and automatically re-evaluates upstream health before
resuming.
## Configuration reference
The [Traffic Policy](/traffic-policy/) configuration reference for this action.
### Supported phases
`on_http_request`
### Type
`circuit-breaker`
### Configuration fields
Threshold percentage of errors that must be met before requests are
rejected.
Must be a value between `0.0` and `1.0`.
Number of requests in a rolling window before checking the error
threshold.
Must be a number between `1` and `2,000,000,000`.
Number of seconds in the rolling window that metrics are retained for.
Must be a value between `1s` and `2m`.
Number of seconds the system waits after rejecting a request before
re-evaluating upstream health.
Must be a value between `1s` and `2m`.
Number of buckets that metrics are divided into within the rolling window.
Fixed at `10`.
Determines if the circuit breaker is active.
If `false`, the circuit breaker never trips, and no requests are rejected.
## Behavior
### 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
### Basic example
This example configuration sets up an endpoint (`hotdog.ngrok.app`) that allows
only 1 request every 60 seconds and trips the circuit breaker for 2 minutes.
#### Example Traffic Policy document
```yaml policy.yml theme={null}
on_http_request:
- actions:
- type: "circuit-breaker"
config:
error_threshold: 0
volume_threshold: 1
window_duration: "60s"
tripped_duration: "2m"
enforce: true
```
```json policy.json theme={null}
{
"on_http_request": [
{
"actions": [
{
"type": "circuit-breaker",
"config": {
"error_threshold": 0,
"volume_threshold": 1,
"window_duration": "60s",
"tripped_duration": "2m",
"enforce": true
}
}
]
}
]
}
```
#### Start endpoint with Traffic Policy
```bash theme={null}
ngrok http 8080 --url hotdog.ngrok.app --traffic-policy-file /path/to/policy.yml
```
#### Helper script
```python circuit_breaker.py theme={null}
import requests
import time
url = "https://hotdog.ngrok.app"
attempt = 1
while True:
try:
response = requests.get(url)
# Log the response
if response.status_code == 200:
print(f"Attempt {attempt}: Success ({response.status_code})")
else:
print(f"Attempt {attempt}: Failure ({response.status_code})")
# Stop when circuit breaker trips
if response.status_code == 503:
print("\nCircuit breaker tripped!")
break
except requests.exceptions.RequestException as e:
print(f"Attempt {attempt}: Error ({e})")
break
attempt += 1
time.sleep(0.01) # Reduce delay for faster request rate
```
```bash theme={null}
➜ ~ python3 circuit_breaker.py
Attempt 1: Success (200)
Attempt 2: Failure (503)
Circuit breaker tripped!
```
## 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.
This action does not expose any result variables.