Calling an external API is one of the most common operations in modern .NET applications. An ASP.NET Core application might communicate with a payment gateway, authentication provider, shipping service, notification platform, or another internal microservice.
These integrations usually work well during normal conditions. The problems begin when the external service becomes slow, temporarily unavailable, or overloaded.
Imagine an e-commerce application processing an order. The application sends a request to a payment service, but the payment service takes several seconds to respond. The request eventually times out. The application tries again, but the second request also fails.
Without a proper strategy, the application may continue sending requests to an already unhealthy service. This increases network traffic, consumes application resources, and can make the external service recover more slowly.
A reliable HTTP integration needs more than a timeout and a retry loop. It needs a combination of connection management, controlled retries, circuit breaking, request timeouts, and clear failure handling.
.NET provides IHttpClientFactory for managing HTTP clients, while Microsoft.Extensions.Http.Resilience provides built-in resilience strategies for HTTP requests.
Understanding how these features work together helps developers build applications that handle temporary failures without creating additional problems.
Why Ordinary HTTP Requests Are Not Enough
Consider a simple HTTP request:
using var client = new HttpClient();
var response = await client.GetAsync(
"https://api.example.com/products");
response.EnsureSuccessStatusCode();
var content = await response.Content.ReadAsStringAsync();
This code works, but it does not address several production concerns.
The application creates an HttpClient instance directly, does not define an explicit request timeout, and has no resilience strategy for transient failures.
Creating and disposing HttpClient repeatedly can also lead to connection-management problems if the underlying handlers and connections are not managed appropriately.
Another common mistake is keeping a single static HttpClient forever without considering DNS changes or connection lifetime.
HttpClient uses connection pools. DNS resolution occurs when a connection is created, and an existing connection does not automatically follow every DNS change.
This matters when an application communicates with services behind load balancers, containers, or cloud infrastructure where endpoint addresses can change.
The goal is not simply to reuse an HttpClient object. The goal is to manage the underlying connections correctly and handle failures in a controlled way.
Use IHttpClientFactory to Manage HTTP Clients
IHttpClientFactory provides a centralized way to create and configure HttpClient instances through dependency injection.
It manages the lifetime of underlying HttpMessageHandler instances and supports named and typed clients.
Start by registering the HTTP client:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient();
var app = builder.Build();
app.Run();
You can then inject IHttpClientFactory into a service:
public class ProductService
{
private readonly IHttpClientFactory _httpClientFactory;
public ProductService(IHttpClientFactory httpClientFactory)
{
_httpClientFactory = httpClientFactory;
}
public async Task<string> GetProductsAsync(
CancellationToken cancellationToken)
{
var client = _httpClientFactory.CreateClient();
var response = await client.GetAsync(
"https://api.example.com/products",
cancellationToken);
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsStringAsync(
cancellationToken);
}
}
The factory creates a new HttpClient instance when requested, while managing and reusing underlying handlers.
This helps avoid common connection exhaustion problems associated with creating and disposing independent handlers for every request.
It also provides a convenient place to configure base addresses, default headers, logging, and resilience handlers.
Use Typed Clients for External Services
As an application grows, it is better to create a dedicated HTTP client for each external dependency.
For example, a payment integration should not share unrelated configuration with a shipping service.
A typed client provides a strongly typed interface for communicating with a particular API.
Create a service:
public class PaymentApiClient
{
private readonly HttpClient _httpClient;
public PaymentApiClient(HttpClient httpClient)
{
_httpClient = httpClient;
}
public async Task<string> GetPaymentStatusAsync(
string paymentId,
CancellationToken cancellationToken)
{
var response = await _httpClient.GetAsync(
$"payments/{paymentId}",
cancellationToken);
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsStringAsync(
cancellationToken);
}
}
Register the typed client:
builder.Services.AddHttpClient<PaymentApiClient>(client =>
{
client.BaseAddress = new Uri(
"https://payments.example.com/");
client.Timeout = TimeSpan.FromSeconds(20);
});
Now the application can inject PaymentApiClient wherever payment information is required.
This approach keeps HTTP configuration separate from business logic.
It also makes testing easier because the service can be tested using a controlled HTTP message handler rather than requiring a real payment service.
Add Resilience With Microsoft.Extensions.Http.Resilience
The Microsoft.Extensions.Http.Resilience package provides resilience mechanisms specifically designed for HttpClient.
Install it using:
dotnet add package Microsoft.Extensions.Http.Resilience
You can add the standard resilience handler to a typed client:
builder.Services
.AddHttpClient<PaymentApiClient>(client =>
{
client.BaseAddress = new Uri(
"https://payments.example.com/");
})
.AddStandardResilienceHandler();
This configures a standard resilience pipeline for outgoing HTTP requests.
The standard handler combines multiple strategies:
- Rate limiting controls the number of concurrent requests.
- Total timeout limits the overall duration of a request, including retries.
- Retry handles selected transient failures.
- Circuit breaker prevents repeated calls to an unhealthy dependency.
- Attempt timeout limits the duration of an individual attempt.
These strategies work together rather than operating as unrelated features.
The standard handler provides useful defaults, but production applications should still review the settings according to the behavior and requirements of each external service.
Do not assume that one default configuration is appropriate for every dependency.
Understand When an HTTP Request Should Be Retried
Retries are useful when a failure is temporary.
For example, an external service might return HTTP 503 because it is temporarily overloaded. A later request may succeed after the service recovers.
However, not every failure is temporary.
Consider these responses:
| HTTP status | Typical interpretation | Retry consideration |
|---|
| 400 | Invalid request | Usually do not retry |
| 401 | Authentication required or invalid | Correct authentication first |
| 403 | Access denied | Usually do not retry |
| 404 | Resource not found | Usually do not retry |
| 408 | Request timeout | May be transient |
| 429 | Too many requests | Respect Retry-After when applicable |
| 500 | Server error | Depends on the failure |
| 502 | Bad gateway | Often transient |
| 503 | Service unavailable | Often transient |
| 504 | Gateway timeout | Often transient |
The standard resilience handler includes retry behavior for selected transient HTTP failures.
However, retrying a request is safe only when the operation itself can tolerate being repeated.
A GET request that retrieves product information is generally safe to retry.
A POST request that creates a payment or submits an order is different.
Suppose the payment service processes a payment successfully, but the response is lost because of a network failure.
The application cannot know whether the payment was completed.
If it blindly retries the POST request, the customer might be charged twice.
For operations that create or modify important business data, use an idempotency mechanism.
For example, the application can generate a unique idempotency key for a payment operation:
var request = new HttpRequestMessage(
HttpMethod.Post,
"payments");
request.Headers.Add(
"Idempotency-Key",
paymentRequest.IdempotencyKey);
The external service must support and correctly implement this behavior. Sending an idempotency header does not automatically make an operation safe if the server ignores it.
The same logical operation should reuse the same key across retries. A new key for every retry can defeat the purpose.
Understand Exponential Backoff and Retry Delays
Retrying immediately after a failure can increase pressure on an unhealthy service.
Suppose 1,000 application instances receive a timeout at the same moment. If all instances retry immediately, the external service receives another large burst of requests.
A better strategy is exponential backoff.
The delay increases between successive attempts.
A simplified example looks like this:
Attempt 1: Immediate request
Attempt 2: Wait 1 second
Attempt 3: Wait 2 seconds
Attempt 4: Wait 4 seconds
The exact delays depend on the configured retry strategy.
Jitter can also be introduced to prevent many clients from retrying at exactly the same time.
This is particularly useful when multiple application instances depend on the same external service.
The standard resilience handler includes retry behavior and configurable backoff options.
For example:
builder.Services
.AddHttpClient<PaymentApiClient>()
.AddStandardResilienceHandler(options =>
{
options.Retry.MaxRetryAttempts = 3;
options.Retry.Delay =
TimeSpan.FromSeconds(1);
options.Retry.BackoffType =
Polly.DelayBackoffType.Exponential;
options.Retry.UseJitter = true;
});
The configuration should be reviewed against the total request timeout and the service's rate limits.
More retries do not automatically mean better reliability. They can increase latency and consume additional resources when a dependency remains unavailable.
Use a Circuit Breaker to Stop Calling an Unhealthy Service
Retries help with temporary failures, but they are not enough when an external service remains unavailable.
Imagine that the payment service is experiencing a prolonged outage.
Every request from the application fails. If the application continues retrying, it wastes time and creates additional traffic.
A circuit breaker helps prevent this behavior.
It generally operates through three states.
Closed: Requests are allowed to reach the external service.
Open: Requests are rejected or short-circuited because the dependency has experienced too many failures.
Half-open: After a configured interval, a limited number of requests are allowed to check whether the service has recovered.
The standard resilience handler includes a circuit breaker strategy.
You can customize its behavior:
builder.Services
.AddHttpClient<PaymentApiClient>()
.AddStandardResilienceHandler(options =>
{
options.CircuitBreaker.FailureRatio = 0.5;
options.CircuitBreaker.MinimumThroughput = 20;
options.CircuitBreaker.SamplingDuration =
TimeSpan.FromSeconds(30);
options.CircuitBreaker.BreakDuration =
TimeSpan.FromSeconds(15);
});
These values are illustrative. The appropriate settings depend on request volume, dependency latency, and acceptable failure behavior.
A circuit breaker does not repair the external service. It protects your application from repeatedly waiting on a dependency that is already failing.
Your application still needs to decide what to return to users when the circuit is open.
For example, a product catalog might display cached information, while a payment operation should clearly report that payment processing is temporarily unavailable.
Do not silently report a payment as successful simply because the external service cannot be reached.
Configure Timeouts at the Correct Level
Timeouts prevent requests from waiting indefinitely.
However, there is an important difference between an overall request timeout and an individual attempt timeout.
Consider a request with multiple retry attempts.
If every attempt is allowed to run for 20 seconds, the overall operation may take much longer than expected.
A total timeout limits the complete operation, including retry delays and attempts.
An attempt timeout limits one individual request attempt.
The standard resilience handler provides both.
You should also consider the timeout of the application endpoint that initiated the external call.
For example, if an API endpoint has a 10-second response budget, configuring an outgoing dependency call with a 30-second timeout may not be useful.
The caller may already have disconnected before the dependency request finishes.
Pass cancellation tokens through the entire request flow:
public async Task<string> GetPaymentAsync(
string paymentId,
CancellationToken cancellationToken)
{
var response = await _httpClient.GetAsync(
$"payments/{paymentId}",
cancellationToken);
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsStringAsync(
cancellationToken);
}
This allows cancellation to propagate when the incoming request is cancelled or the application is shutting down.
Avoid creating unrelated cancellation tokens that prevent the original cancellation request from reaching the HTTP operation.
Avoid Stacking Multiple Resilience Handlers
A common mistake is adding multiple retry mechanisms to the same HTTP client.
For example, an application might add a standard resilience handler and then add another custom retry handler.
This can result in nested retries.
If one handler retries three times and another retries three times, the total number of attempts can become much larger than expected.
This increases request volume and latency.
Microsoft recommends using one resilience handler for a client rather than stacking multiple resilience handlers.
When a custom pipeline is required, use AddResilienceHandler to define the strategies in one place.
Different external dependencies may need different policies.
A payment service, reporting service, and product catalog should not necessarily share identical timeout and retry settings.
Configure them according to their business behavior.
Monitor HTTP Failures and Retry Behavior
A resilient HTTP client should be observable.
Without monitoring, retries can hide an external service problem.
For example, the application might continue returning successful responses because retries eventually succeed, even though the external service is experiencing frequent failures.
Monitor:
- Request duration.
- HTTP status codes.
- Timeout counts.
- Retry attempts.
- Circuit breaker state changes.
- Rate limiter rejections.
- External dependency availability.
Use structured logging and distributed tracing to correlate an incoming application request with its outgoing HTTP calls.
Avoid logging authorization headers, API keys, access tokens, or sensitive request bodies.
For important integrations, include dependency-specific metrics so that failures in one external service can be distinguished from failures in another.
This makes it easier to identify whether a problem originates in your application, network infrastructure, or external dependency.
Production Practices for Resilient HTTP Clients
A few practices make HTTP integrations more reliable.
Use IHttpClientFactory or a carefully managed long-lived HttpClient instead of creating independent handlers for every request.
Use typed clients to isolate external service configuration.
Configure explicit timeouts based on the application's response requirements.
Retry only failures that are likely to be transient.
Use idempotency keys for operations that must not be duplicated.
Apply circuit breakers to protect applications from repeatedly calling unhealthy dependencies.
Respect external service rate limits and Retry-After instructions.
Pass cancellation tokens through HTTP operations.
Avoid stacking multiple retry and resilience handlers.
Monitor retries and failures instead of treating successful final responses as proof that the dependency is healthy.
Summary
Building resilient HTTP clients in .NET requires more than adding a retry loop around GetAsync or PostAsync.
IHttpClientFactory provides a consistent way to create and configure HTTP clients while managing their underlying handlers. Typed clients help organize external service integrations, and Microsoft.Extensions.Http.Resilience provides standard strategies for retries, timeouts, circuit breakers, and rate limiting.
The most important decision is knowing when not to retry.
A temporary network failure may justify another attempt, but an invalid request or a payment operation with an uncertain outcome requires a different response.
By combining controlled retries, idempotency, appropriate timeouts, circuit breakers, and monitoring, .NET applications can handle external service failures without creating additional load or compromising business operations.
Join the conversation! Your thoughts help the community grow.