CONCEPT Stop calling something that's clearly down
Retries and fallbacks (6.1) handle a single failed call. But when a dependency — the Messages API, a tool backend, an MCP server — is sustained-down, retrying every request just piles load onto a struggling service, burns your latency budget waiting for timeouts, and makes recovery slower. A circuit breaker watches the failure rate and, once it crosses a threshold, trips open: subsequent calls fail immediately (or route straight to a fallback) without touching the sick dependency.
CONCEPT Three states: closed → open → half-open
The breaker is a tiny state machine wrapped around the call site.
| State | Behavior | Transition out |
|---|---|---|
| 🟢 Closed (normal) | Calls pass through; count failures | Failures cross the threshold → Open |
| 🔴 Open (tripped) | Calls fail fast / route to fallback — dependency is not touched | After a cooldown timer → Half-open |
| 🟠 Half-open (probing) | Let one trial request through | Success → Closed (recovered); failure → back to Open |
DIAGRAM The breaker state machine
CODE A minimal circuit breaker for a model client
When open, calls short-circuit to the fallback from 6.1 instead of hitting the overloaded dependency.
class CircuitBreaker: def __init__(self, threshold=5, cooldown=30): self.threshold, self.cooldown = threshold, cooldown self.failures, self.opened_at = 0, None def call(self, fn, *args): if self.opened_at: # OPEN if time() - self.opened_at < self.cooldown: raise CircuitOpen() # fail fast → 6.1 fallback self.opened_at = None # cooldown done → HALF-OPEN probe try: result = fn(*args) # trial (half-open) or normal self.failures = 0 # success → CLOSED, reset return result except (anthropic.APIStatusError, anthropic.APIConnectionError): self.failures += 1 if self.failures >= self.threshold: self.opened_at = time() # trip OPEN raise
TRADE-OFFS Breaker vs. retry-forever
✅ Circuit breaker
- Fails fast instead of waiting on timeouts
- Sheds load so the dependency can recover
- Half-open probe auto-recovers without a deploy
⚠️ Retry every request forever
- Piles load onto an already-struggling service
- Every caller eats the full timeout → cascading slowness
- No automatic "is it back yet?" signal
EXAM TRAPS
PRACTICE
Q1 · What does the breaker do while it's open, and why?
It fails fast — rejecting calls immediately (or routing to a fallback) without touching the sick dependency. This sheds load so the struggling service can recover, and stops callers from blocking on timeouts.
Q2 · How does an open breaker ever close again?
After a cooldown timer it moves to half-open and allows a single trial request. If that probe succeeds, it closes (recovered); if it fails, it re-opens and waits another cooldown. That's the automatic recovery loop.
Q3 · How do breakers, retries, and fallbacks fit together?
Layered: the SDK retries individual 429/5xx blips; a circuit breaker trips when failures form a sustained pattern and stops hammering the dependency; while open it hands off to a fallback (6.1) or degraded mode (6.3) so the user still gets a response.