Circuit Breaker
Overview​
The Circuit Breaker policy is designed to prevent cascading failures in microservices architecture by monitoring the health of upstream services and blocking requests when a service becomes unstable. This ensures system stability, improved user experience, and faster recovery from failures.
The Circuit Breaker transitions between three states:
- Closed: Requests are processed normally.
- Open: Requests are blocked due to high failure rates.
- Half-Open: A limited number of test requests are sent to check if the service has recovered.
This policy helps prevent excessive retries, reduce latency, and ensure fault tolerance in distributed systems.
Configuration Details​
Field Configuration​
The Circuit Breaker policy provides several configurable parameters that determine when and how requests are blocked based on system failures.
| Field name | Key​ | Type​ | Required​ | Description​ |
|---|---|---|---|---|
| Error measurement unit time (s) | window_time | number​ | true​ | Window size in seconds​ |
| Error rate (%) | failure_percent_threshold​ | number​ | true​ | % of requests that should fail to open the circuit​ |
| Minimum number of requests* | min_calls_in_window | number​ | true​ | Minimum number of calls to be present in the window to start calculation​ |
| api timeout setting (ms) | api_call_timeout_ms​ | number​ | true​ | Duration to wait before request is timed out and counted as failure​ |
| Open state duration (s) | wait_duration_in_open_state​ | number​ | true​ | Duration(sec) to wait before automatically transitioning from open to half-open state​ |
| Haft-open state duration (s) | wait_duration_in_half_open_state​ | number​ | true​ | Duration(sec) to wait in half-open state before automatically transitioning to closed state​ |
| Minimum (min) number of requests in haft-open state* | half_open_min_calls_in_window​ | number​ | true​ | Minimum number of calls to be present in the half open state to start calculation​ |
| Maximum number of requests in haft-open state* | half_open_max_calls_in_window​ | number​ | true​ | Maximum calls to allow in half open state​ |
| Set response error code* | error_status_code​ | number​ | false​ | Override response status code in case of error (circuit-breaker blocks the request)​ |
| Set response error message* | error_msg_override​ | string​ | false​ | Override with custom message in case of error​ |
| Set response header* | response_header_override​ | string​ | false​ | Override "Content-Type" response header in case of error​ |
| Set exception path* | excluded_apis​ | string​ | true​ | Stringified json to prevent running circuit-breaker on these APIs​. Can add or delete additional paths by clicking on plus or minus button on each path. |
| Active fallback path | fallback path | string | false | A fallback path is defined to handle requests when the main service is unavailable. |
Additional Notes on Circuit Breaker Behavior​
The Circuit Breaker operates based on a failure detection cycle and transitions through three states:
- Closed: Normal state where traffic passes through and error rate is monitored.
- Open: Triggered when the error rate threshold is exceeded, blocking all incoming traffic temporarily.
- Half-Open: After a configured time, limited traffic is allowed to test system recovery.
- Recovery: If test traffic passes without issues, the system returns to normal (Closed).
Each setting contributes to controlling this lifecycle:
| Field | Description |
|---|---|
| Minimum Requests | Minimum number of requests within the unit time to start measuring errors. |
| API Timeout | If a request exceeds this threshold, it’s treated as a failure. |
| Open State Duration | Duration (in seconds) the circuit remains open. |
| Half-Open Duration | Duration (in seconds) the circuit remains in half-open state. |
| Min Requests in Half-Open | Minimum traffic required during half-open to start observing error rate again. |
| Max Requests in Half-Open | Max number of test requests to evaluate recovery. |
Response Configuration Options​
- Custom Error Code: Error code returned when traffic is blocked.
- Custom Error Message: Message body returned when traffic is blocked.
- Custom Error Content-Type: Content-Type of the error response.
Exception Path Configuration​
Define specific paths where the circuit breaker should not be applied.
Format: METHOD + PATH
e.g., GET /example/v1
Fallback Path Configuration​
If the circuit breaker is activated, requests can be redirected to an alternate page:
- Fallback Path allows defining a custom redirection route for blocked requests.
- Default Path will be used unless a Fallback Path is defined.
- To redirect to a specific path in the same API, specify the desired API PATH as the Fallback Path.
