Preserve OperationCanceledException for explicitly requested cancellation instead of being wrapping it in ApiRequestException

[Nathanael59]

Hi,

First of all, thanks for the amazing work on Refit 11! I understand the motivation behind #2052. Having ApiRequestException and a unified ApiExceptionBase model is a valuable improvement.

I would like to discuss one specific edge case though: caller-requested cancellation.

Since v11.0, all exceptions thrown by HttpClient.SendAsync are wrapped into ApiRequestException:

refit/src/Refit/RequestExecutionHelpers.cs

Lines 322 to 351 in 196cd49

	private static async Task<SendResult<T>> SendOrCaptureExceptionAsync<T, TBody>(
	HttpClient client,
	HttpRequestMessage request,
	RefitSettings settings,
	bool isApiResponse,
	CancellationToken cancellationToken)
	{
	try
	{
	var response = await client
	.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, cancellationToken)
	.ConfigureAwait(false);
	return SendResult<T>.FromResponse(response);
	}
	catch (Exception ex)
	{
	if (!isApiResponse)
	{
	throw new ApiRequestException(request, request.Method, settings, ex);
	}
	var failure = ApiResponse.Create<T, TBody>(
	request,
	null,
	default,
	settings,
	new ApiRequestException(request, request.Method, settings, ex));
	return SendResult<T>.FromFailure(failure);
	}
	}

However, I think there is an important semantic difference between:

• a request failing because the transport layer failed or timed out;
• a request being cancelled because the caller explicitly requested cancellation through the provided CancellationToken.

OperationCanceledException caused by the caller’s token cancellation is generally not treated as an application/infrastructure error. It is control flow. Many applications intentionally let it bubble up so that ASP.NET Core, background workers, logging middleware, retry policies, and tracing systems can classify it correctly as cancellation rather than failure.

I would normally expect this pattern to keep working:

try
{
    return await api.GetSomethingAsync(cancellationToken);
}
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
{
    throw;
}
catch (ApiExceptionBase ex)
{
    // real API / transport failure
}

With the current v11 behavior, it requires something closer to:

catch (ApiRequestException ex)
    when (cancellationToken.IsCancellationRequested &&
          ex.InnerException is OperationCanceledException)
{
    ExceptionDispatchInfo.Capture(ex.InnerException).Throw(); // rethrow the OperationCanceledException
}

or a bit more tricky with the ApiResponse way

var response = await client.GetSomethingAsync(cancellationToken);

if (response.HasRequestError(out var requestError) &&
    cancellationToken.IsCancellationRequested &&
    requestError.InnerException is OperationCanceledException)
{
    ExceptionDispatchInfo.Capture(ex.InnerException).Throw(); // rethrow the OperationCanceledException
}

I am not arguing against ApiRequestException in general. The new model is useful for real transport failures and for carrying request context. My concern is specifically about intentional cancellation, which usually has a different semantic from a failed http request and is expected to bubble up as is.

What's your point of view on that?

Thank you!

[glennawatson]

I can see your position on the way we do ApiExceptions, so potentially it's likely a regression in some regards. Probably worth raising an issue.

[glennawatson]

Agreed - wrapping a caller-requested cancellation (OperationCanceledException from your own CancellationToken) in ApiRequestException is a regression from the pre-v11 behavior. Intentional cancellation is control flow, not a transport error, and should propagate unwrapped so ASP.NET Core abort handling, Polly, and plain catch (OperationCanceledException) work as expected.

I've opened a tracking issue with repro, the timeout-vs-cancellation distinction, and implementation/test notes: #2188

Genuine HttpClient.Timeout cancellations (token not signalled) will keep the current ApiRequestException wrapping so real timeouts are still reported as request errors. Let's continue on the issue.