Skip to main content
Available on all Portkey plans.
Circuit breakers prevent cascading failures by temporarily blocking requests to targets that are failing.

Config Schema

  • Strategies inherit cb_config from parent if not set
  • Targets inherit from their parent strategy
conditional mode strategies are not evaluated by circuit breaker.

Example

The @provider-slug/model-name format automatically routes to the correct provider. Set up providers in Model Catalog.

How It Works

Circuit breaker tracks per strategy path:
  • Failure and success counts
  • Time of first failure
  • Failure rate (when minimum_requests threshold met)
Circuit opens (OPEN) when:
  • Failure count exceeds failure_threshold, or
  • Failure rate exceeds failure_threshold_percentage
Circuit closes (CLOSED) automatically after cooldown_interval passes.

Runtime Behavior

  • Unhealthy targets removed from routing
  • If all targets are OPEN, circuit breaker is bypassed

Where Circuit Breakers Fit

Circuit breakers protect your setup from unhealthy targets. They watch for failures and open when a target stops responding reliably, so the gateway can route around it until it recovers. Circuit breakers are failure-based. They open when failures cross your configured thresholds, and they don’t limit how many requests run in parallel. If your goal is to shape traffic or manage load, for example handling bursts of parallel requests, these work well alongside circuit breakers in a config:
  • Rate limits to cap requests or tokens on a provider or integration
  • Load balancing to spread traffic across targets by weight
  • Fallbacks to route to a backup target when a request fails
Each handles its own part. For example, if a provider returns 429 under heavy load and 429 is in failure_status_codes, the circuit breaker counts those responses as failures and can open the circuit, while your fallback or load balancing strategy decides where traffic goes next.

Portkey is now PRISMA AIRS AI Gateway. See it in action.

Contact Us
Last modified on November 9, 2026