Circuit Breaker Pattern in .NET

A circuit breaker temporarily rejects calls after a dependency's failure rate reaches a configured threshold. In .NET, Polly tracks outcomes across calls, opens the circuit for a break duration, and then allows a trial call to test recovery. Retries and timeouts complement the breaker but need their own limits and failure predicates.

Why Circuit Breakers?

Imagine your service calls a payment API. The API goes down. Without a circuit breaker:

1. Every request waits for the payment API to respond
2. Outstanding calls retain memory and occupy connection capacity
3. Retrying callers increase pressure on the dependency
4. Latency and resource exhaustion can spread to your service

Asynchronous I/O releases its thread while waiting. Thread pool exhaustion is a separate risk if you block on async calls with .Result or .Wait().

A retry pattern helps with transient failures, but when a service stays down, retrying adds load to an already struggling system.

The circuit breaker solves this by failing fast when it detects the downstream service is unhealthy.

How It Works

The circuit breaker has three states:

Closed (normal): All calls pass through. The circuit breaker monitors success and failure rates.

Open (tripped): After too many failures, the circuit breaker opens. All calls are immediately rejected without attempting the downstream call.

Half-Open (testing): After the break duration, the next call becomes a trial call in Polly. Other callers remain blocked while that trial runs; its outcome determines whether the breaker closes or reopens.

Implementation With Polly

Create a .NET 10 web project with dotnet new web -n CircuitDemo and install the HTTP resilience package, which also brings in Polly's dependency-injection integration:

dotnet add package Microsoft.Extensions.Http.Resilience

Use these namespaces in Program.cs:

using System.Net;
using System.Net.Http.Json;
using Microsoft.Extensions.Http.Resilience;
using Polly;
using Polly.CircuitBreaker;
using Polly.Registry;
using Polly.Retry;
using Polly.Timeout;

Register a shared Polly pipeline before builder.Build():

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddResiliencePipeline("payment-api", pipeline =>
{
    pipeline.AddCircuitBreaker(new CircuitBreakerStrategyOptions
    {
        FailureRatio = 0.5,                             // Open after 50% failure rate
        SamplingDuration = TimeSpan.FromSeconds(30),     // Measure over 30-second windows
        MinimumThroughput = 10,                          // Need at least 10 calls to evaluate
        BreakDuration = TimeSpan.FromSeconds(30),        // Stay open for 30 seconds
        ShouldHandle = new PredicateBuilder()
            .Handle<HttpRequestException>(TransientHttp.IsFailure)
            .Handle<TimeoutRejectedException>()
    });
    pipeline.AddTimeout(TimeSpan.FromSeconds(5));
});

Use this predicate when an HTTP method such as GetFromJsonAsync converts status errors into exceptions:

public static class TransientHttp
{
    public static bool IsFailure(HttpRequestException exception) =>
        exception.StatusCode is null or HttpStatusCode.RequestTimeout
            or HttpStatusCode.TooManyRequests ||
        (int)exception.StatusCode.Value >= 500;
}

The breaker records failures and rethrows them; it does not retry or substitute a result. Resolve and reuse this pipeline through the registry so its state survives individual calls.

Parameters explained:

• FailureRatio: the percentage of failed calls that triggers the circuit breaker
• SamplingDuration: the time window over which failures are counted
• MinimumThroughput: minimum number of calls before the ratio is evaluated (prevents opening on a single failure)
• BreakDuration: how long the circuit stays open before moving to half-open

Circuit Breaker for HTTP Clients

The most common use case is protecting HTTP calls to external APIs:

builder.Services.AddHttpClient("PaymentApi", client =>
{
    client.BaseAddress = new Uri("https://payments.example.com");
})
.AddResilienceHandler("circuit-breaker", pipeline =>
{
    pipeline.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions
    {
        FailureRatio = 0.5,
        SamplingDuration = TimeSpan.FromSeconds(30),
        MinimumThroughput = 10,
        BreakDuration = TimeSpan.FromSeconds(60)
    });
    pipeline.AddTimeout(TimeSpan.FromSeconds(5));
});

Or use the standard resilience handler that includes retry + circuit breaker + timeout:

builder.Services.AddHttpClient("PaymentApi")
    .AddStandardResilienceHandler(options =>
        options.Retry.DisableForUnsafeHttpMethods());

Choose one registration for a given client. The standard handler retries all HTTP methods by default, so the example disables retries for unsafe methods until their side effects have an explicit idempotency contract. Its breaker observes HTTP responses, including 408, 429, and 5xx, without requiring EnsureSuccessStatusCode().

I covered how to customize these defaults in overriding default HTTP resilience handlers in .NET.

Combining Retry and Circuit Breaker

Strategies execute in the order you add them, first added outermost. Put retry outside the circuit breaker when you want the breaker to count each attempt:

builder.Services.AddResiliencePipeline("external-api", pipeline =>
{
    pipeline.AddTimeout(TimeSpan.FromSeconds(20));

    // Retry (outer) - handles transient failures with backoff
    pipeline.AddRetry(new RetryStrategyOptions
    {
        MaxRetryAttempts = 3,
        BackoffType = DelayBackoffType.Exponential,
        Delay = TimeSpan.FromMilliseconds(500),
        UseJitter = true,
        ShouldHandle = new PredicateBuilder()
            .Handle<HttpRequestException>(TransientHttp.IsFailure)
            .Handle<TimeoutRejectedException>()
    });

    // Circuit breaker - stops calls when the service is down
    pipeline.AddCircuitBreaker(new CircuitBreakerStrategyOptions
    {
        FailureRatio = 0.5,
        SamplingDuration = TimeSpan.FromSeconds(30),
        MinimumThroughput = 10,
        BreakDuration = TimeSpan.FromSeconds(30),
        ShouldHandle = new PredicateBuilder()
            .Handle<HttpRequestException>(TransientHttp.IsFailure)
            .Handle<TimeoutRejectedException>()
    });

    // Timeout (innermost) - per-attempt timeout
    pipeline.AddTimeout(TimeSpan.FromSeconds(5));
});

The flow:

1. The retry strategy allows the original attempt plus up to three retries with backoff and jitter
2. Each attempt passes through the circuit breaker; an open circuit throws BrokenCircuitException, which this retry predicate excludes
3. Each attempt that reaches the network has a 5-second timeout
4. The outer timeout caps the entire operation, including backoff, at 20 seconds

This ordering is what .NET's own AddStandardResilienceHandler uses. When the circuit opens, the current operation stops as soon as an attempt encounters it. If retry goes inside the breaker, the breaker instead records one final outcome per logical operation. That is a different measurement boundary, and can be appropriate when you want to count operations rather than individual attempts.

Handling the Open Circuit

For a runnable read-only example, use the payment-api pipeline above and add this registration and endpoint before the type declarations in Program.cs:

builder.Services.AddHttpClient("PaymentStatus", client =>
    client.BaseAddress = new Uri("https://payments.example.com"));

var app = builder.Build();
app.MapGet("/payments/{id:guid}", async (
    Guid id, IHttpClientFactory clients,
    ResiliencePipelineProvider<string> pipelines, CancellationToken ct) =>
{
    var pipeline = pipelines.GetPipeline("payment-api");
    var client = clients.CreateClient("PaymentStatus");
    try
    {
        var result = await pipeline.ExecuteAsync(async token =>
        {
            return await client.GetFromJsonAsync<PaymentStatus>(
                $"/api/payments/{id}", token)
                ?? throw new InvalidOperationException("Empty payment response.");
        }, ct);
        return Results.Ok(result);
    }
    catch (BrokenCircuitException)
    {
        return Results.StatusCode(StatusCodes.Status503ServiceUnavailable);
    }
});
app.Run();

public sealed record PaymentStatus(Guid Id, string Status);

This endpoint maps an open circuit to 503; use your normal exception handling for other upstream errors and timeouts. A fallback may return cached data when the contract allows it. Never claim that a payment was queued unless you have durably queued it, and never retry a payment POST without server-side idempotency.

Listening for State Changes

Monitor state transitions when configuring the breaker. For example, with an ILogger named logger available in the registration callback:

pipeline.AddCircuitBreaker(new CircuitBreakerStrategyOptions
{
    FailureRatio = 0.5,
    SamplingDuration = TimeSpan.FromSeconds(30),
    MinimumThroughput = 10,
    BreakDuration = TimeSpan.FromSeconds(30),
    ShouldHandle = new PredicateBuilder()
        .Handle<HttpRequestException>(TransientHttp.IsFailure)
        .Handle<TimeoutRejectedException>(),
    OnOpened = args =>
    {
        logger.LogWarning(
            "Circuit opened for {Duration}. Reason: {Reason}",
            args.BreakDuration,
            args.Outcome.Exception?.Message);
        return ValueTask.CompletedTask;
    },
    OnClosed = _ =>
    {
        logger.LogInformation("Circuit closed - service recovered");
        return ValueTask.CompletedTask;
    },
    OnHalfOpened = _ =>
    {
        logger.LogInformation("Circuit half-opened - testing recovery");
        return ValueTask.CompletedTask;
    }
});

Use these events for alerting and dashboards.

Circuit Breaker vs Retry

The two patterns answer different failure modes:

• Retry handles transient, momentary failures. It repeats the same call after a brief delay. It works well for a blip in connectivity, but blind retries can overwhelm a service that's already struggling.
• Circuit breaker handles prolonged outages. It stops calling the failing service entirely for a period. It helps most when the dependency stays down, at the risk of rejecting calls slightly too aggressively during recovery.

They complement each other, which is why the pipeline above uses both. I've written a dedicated comparison in retry vs circuit breaker if you're deciding which to reach for first.

Practical Configuration Tips

1. Set MinimumThroughput high enough. A single failed call shouldn't open the circuit. Use 10-20 as a starting point.

2. Match BreakDuration to your recovery time. If the downstream service typically recovers in 30 seconds, set the break to 30-60 seconds.

3. Monitor your circuits. Use OpenTelemetry or logs to track when circuits open and close. Frequent opens indicate a reliability problem.

4. Use per-service circuit breakers. Don't share one circuit breaker across all calls. A failing payment service shouldn't break your email service.

5. Combine with health checks. If a circuit opens frequently, the health check can mark the service as degraded.

Summary

The circuit breaker pattern prevents cascading failures by failing fast when a downstream service is unhealthy.

Reuse a breaker per dependency, count only the failures relevant to that dependency, and monitor state transitions.

Start with the standard HTTP resilience handler for HTTP clients and configure which methods may be retried. For the bigger picture of resilience in cloud systems, see building resilient cloud applications with .NET.