---
schema_version: "1"
id: 2100fd1f51782090e725bd6cbd6dd17fa892a03a86c454b9900fef5b4cb23f58
title: Circuit Breaker Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/latest/policies-outbound-circuit-breaker.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-outbound-circuit-breaker
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 2727e0ce5e118224c6b84901230ff5dec0086dd90d1f517b67dfffa783986c53
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
---

# Circuit Breaker Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Circuit Breaker</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Prevents an upstream from receiving too many requests or connections</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Quality of Service</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.9.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-circuit-breaker-release-notes">Circuit Breaker</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>503 - Service Unavailable</p></div></div></td></tr></tbody></table>

## Summary

The Circuit Breaker policy prevents upstream services from receiving too many requests or
connections at a time. If the defined maximums are reached, Omni Gateway returns a
`503 - Service Unavailable` error.

This policy overrides the circuit breaker thresholds set in Runtime Manager or a Configuration
resource for the API instance you apply it to. To change the gateway-level thresholds, see
[Configure Circuit Breaker for Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/managed-circuit-breaker) or
[Configure Circuit Breaker in Connected Mode](https://docs.mulesoft.com/gateway/latest/conn-circuit-breaker).

For Managed Omni Gateways or Connected Mode, each API instance has its own independent limit when
requesting the same upstream, allowing each to use the full maximum. In Local Mode, the limits are
shared among different API instances, so they must all adhere to the same upstream maximum. For all
modes, maximums are not distributed across replicas; each Gateway can use the full maximum.

The Circuit Breaker policy is an extension of the Envoy upstream clusters circuit breaking feature.
To learn more about the Envoy’s circuit breaking, see
[Circuit Breaking](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html)
in the Envoy documentation.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: upstream-policy spec:
targetRef: Kind: Service name: upstream policyRef: name: circuit-breaker-flex config: thresholds:
maxConnections: <number> // OPTIONAL maxPendingRequests: <number> // OPTIONAL maxRequests: <number>
// OPTIONAL maxRetries: <number> // OPTIONAL maxConnectionPools: <number> // OPTIONAL

> [!NOTE] For Local Mode, the limits are not independent, so different API instances share the
> maximums for an upstream.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumConnections</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumPendingRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRequests</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p><code>maximumRetries</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p><code>maximumConnectionPools</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example defines a policy that supports a maximum of one request at a time:

apiVersion: gateway.mulesoft.com/v1beta1 kind: Configuration metadata: name: circuit-breaker
namespace: test-ns spec: circuitBreaker: thresholds: maxConnections: 1 maxPendingRequests: 1
maxRequests: 1 maxRetries: 1 maxConnectionPools: 1

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Maximum connections</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connections per API to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum pending requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of queued requests while waiting for a connection.</p></div></div></td></tr><tr><td><div><div><p>Maximum requests</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding requests to an upstream.</p></div></div></td></tr><tr><td><div><div><p>Maximum retries</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of outstanding retries.</p></div></div></td></tr><tr><td><div><div><p>Maximum connection pools</p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Maximum number of connection pools concurrently initiated to an upstream.</p></div></div></td></tr></tbody></table>

> [!NOTE] For Managed Omni Gateways or Connected Mode, each API instance has its own independent
> limit when requesting the same upstream, allowing each to use the full maximum.