How do you handle timeouts correctly in async .NET code, from HttpClient to ASP.NET Core requests?

1. WaitAsync vs real cancellation

// Stops waiting after 1 s; SlowAsync keeps running, holding a connection/thread/locks
await SlowAsync(CancellationToken.None).WaitAsync(TimeSpan.FromSeconds(1));

// Cancels the work itself
using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
cts.CancelAfter(TimeSpan.FromSeconds(1));
await SlowAsync(cts.Token);

The old Task.WhenAny(work, Task.Delay(timeout)) pattern has the same problem as WaitAsync, plus it leaks the delay timer if not cancelled.

2. HttpClient timeouts in detail

With a resilience handler, set HttpClient.Timeout to Timeout.InfiniteTimeSpan or larger than the total pipeline timeout, otherwise the client's timeout can fire first with a less informative exception.

3. ASP.NET Core request timeouts

builder.Services.AddRequestTimeouts(o =>
{
    o.DefaultPolicy = new RequestTimeoutPolicy { Timeout = TimeSpan.FromSeconds(10) };
    o.AddPolicy("reports", TimeSpan.FromSeconds(60));
});
app.UseRequestTimeouts();

app.MapGet("/report", async (ReportService s, CancellationToken ct) => await s.BuildAsync(ct))
   .WithRequestTimeout("reports");

• The middleware cancels HttpContext.RequestAborted; it doesn't abort threads.
• It's not applied when a debugger is attached (so breakpoints don't trip timeouts).
• If the endpoint ignores its token, the timeout does nothing useful.

4. Retries and timeouts together

total 6 s
├─ attempt 1: 2 s timeout -> times out
├─ backoff 200 ms (+ jitter)
├─ attempt 2: 2 s timeout -> times out
├─ backoff 400 ms
└─ attempt 3: remaining ~1.4 s -> total timeout fires

Only retry idempotent operations (or use idempotency keys). Retrying a non-idempotent POST after a timeout can duplicate side effects because the first attempt may have succeeded.

5. Testing with TimeProvider

public sealed class QuoteService(HttpClient http, TimeProvider time)
{
    public async Task<Quote> GetAsync(CancellationToken ct)
    {
        using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
        cts.CancelAfter(TimeSpan.FromSeconds(2));       // uses real time; for full control create the CTS with time
        await Task.Delay(TimeSpan.FromMilliseconds(100), time, cts.Token);
        return await http.GetFromJsonAsync<Quote>("quote", cts.Token) ?? throw new InvalidOperationException();
    }
}
// Tests: inject FakeTimeProvider and call Advance(...) instead of waiting.

6. Version notes

7. Try it yourself

1. Point an HttpClient with Timeout = 1s at a test endpoint that delays 5 s; print ex.InnerException?.GetType().
2. Compare WaitAsync(1s) vs a linked CTS: log when the server finishes the request in each case.
3. Add AddStandardResilienceHandler with a 1 s attempt and 3 s total timeout, and log retries.
4. Add request timeouts middleware with 2 s and an endpoint that ignores its token; observe the work still running.
5. Make the endpoint honour the token and observe immediate cancellation.
6. Write a test with FakeTimeProvider that asserts a TimeoutException without waiting.

using Microsoft.Extensions.Http.Resilience;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient<FraudClient>(c =>
{
    c.BaseAddress = new Uri("https://fraud.internal/");
    c.Timeout = Timeout.InfiniteTimeSpan; // let the resilience pipeline own timeouts
})
.AddStandardResilienceHandler(o =>
{
    o.AttemptTimeout.Timeout = TimeSpan.FromSeconds(2);
    o.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(6);
    o.Retry.MaxRetryAttempts = 2;
});

builder.Services.AddRequestTimeouts(o =>
    o.DefaultPolicy = new() { Timeout = TimeSpan.FromSeconds(10) });

var app = builder.Build();
app.UseRequestTimeouts();

app.MapPost("/checkout/{orderId:int}", async (int orderId, FraudClient fraud, CancellationToken ct) =>
{
    try
    {
        bool ok = await fraud.CheckAsync(orderId, ct);
        return ok ? Results.Ok() : Results.StatusCode(StatusCodes.Status402PaymentRequired);
    }
    catch (Exception ex) when (ex is TimeoutException or Polly.Timeout.TimeoutRejectedException && !ct.IsCancellationRequested)
    {
        return Results.Accepted(value: "Queued for manual fraud review"); // degrade, do not hang
    }
});

app.Run();

public sealed class FraudClient(HttpClient http)
{
    public async Task<bool> CheckAsync(int orderId, CancellationToken ct)
    {
        using var response = await http.GetAsync($"check/{orderId}", ct);
        return response.IsSuccessStatusCode;
    }
}