diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml
index 4e8bd348933..94e3ffbe519 100644
--- a/xml/System.Net.Http/HttpClient.xml
+++ b/xml/System.Net.Http/HttpClient.xml
@@ -600,7 +600,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
-or-
<see cref="P:System.Net.Http.HttpClient.BaseAddress" /> is not set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response, such as network connectivity failure, DNS failure, server certificate validation error, or invalid server response. On .NET 8 and later versions, the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />.
+
+-or-
+
+.NET Framework only: The request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -673,7 +677,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
-or-
<see cref="P:System.Net.Http.HttpClient.BaseAddress" /> is not set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -752,7 +760,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
-or-
<see cref="P:System.Net.Http.HttpClient.BaseAddress" /> is not set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -831,7 +843,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
-or-
<see cref="P:System.Net.Http.HttpClient.BaseAddress" /> is not set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -974,7 +990,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
</Docs>
@@ -1039,7 +1059,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -1180,7 +1204,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
@@ -1251,7 +1279,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -1317,7 +1349,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">TThe request failed due to an issue getting an HTTP response such as network connectivity, DNS failure or server certificate validation. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -1393,7 +1429,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
@@ -1466,7 +1506,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -1548,6 +1592,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned <xref:System.Threading.Tasks.Task%601> object will complete after the whole response body is read.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of timeout, different exceptions are thrown on different .NET implementations.
@@ -1557,7 +1604,15 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard)
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
</Docs>
@@ -1613,6 +1668,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned <xref:System.Threading.Tasks.Task%601> object will complete after the whole response body is read.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -1623,7 +1681,15 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response, such as network connectivity failure, DNS failure, server certificate validation error, or invalid server response. On .NET 8+, the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />.
+
+-or-
+
+The response status code was outside of the range of 200-299 (which indicate success according to the standard).
+
+-or-
+
+.NET Framework only: The request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -1675,6 +1741,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned <xref:System.Threading.Tasks.Task%601> object will complete after the whole response body is read.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -1684,7 +1753,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard).</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
@@ -1737,6 +1810,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned <xref:System.Threading.Tasks.Task%601> object will complete after the whole response body is read.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -1746,7 +1822,12 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard)
+</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -1828,6 +1909,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned [Task\<Stream>](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read or buffer the response body.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -1837,7 +1921,15 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard)
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
</Docs>
@@ -1893,6 +1985,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned [Task\<Stream>](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -1902,7 +1997,15 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard)
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -1954,6 +2057,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned [Task\<Stream>](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -1968,7 +2074,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
<exception cref="T:System.ArgumentNullException">The <paramref name="requestUri" /> is <see langword="null" />.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard).</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
</Docs>
</Member>
@@ -2016,6 +2126,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned [Task\<Stream>](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -2025,7 +2138,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="requestUri" /> is <see langword="null" />.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard).</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -2107,6 +2224,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned <xref:System.Threading.Tasks.Task%601> object will complete after the whole response body is read.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -2116,7 +2236,15 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard)
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
</Docs>
@@ -2172,6 +2300,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned <xref:System.Threading.Tasks.Task%601> object will complete after the whole response body is read.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -2181,7 +2312,15 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard)
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -2233,6 +2372,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned <xref:System.Threading.Tasks.Task%601> object will complete after the whole response body is read.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -2242,7 +2384,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="requestUri" /> is <see langword="null" />.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard).</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
@@ -2295,6 +2441,9 @@ The <paramref name="requestUri" /> is not an absolute URI.
## Remarks
This operation doesn't block. The returned <xref:System.Threading.Tasks.Task%601> object will complete after the whole response body is read.
+ Internally, this operation uses <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A?displayProperty=nameWithType> to ensure the response status code is in the success range (200-299) and throws an <xref:System.Net.Http.HttpRequestException> if it is not.
+ In some scenarios you may need stronger control defining which status codes are considered to be succesful; for example an API may be expected to always return `200 OK`.
+ In such cases we recommend to use the <xref:System.Net.Http.HttpClient.SendAsync%2A> method and check if <xref:System.Net.Http.HttpResponseMessage.StatusCode?displayProperty=nameWithType> matches the expected value(s).
> [!NOTE]
> In case of a timeout:
@@ -2304,7 +2453,11 @@ The <paramref name="requestUri" /> is not an absolute URI.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="requestUri" /> is <see langword="null" />.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation (or timeout for .NET Framework only).</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+the respose status code was outside of the range of 200-299 (status codes indicating success according to the standard).</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -2420,6 +2573,9 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
+ <exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> is not an absolute URI and <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> isn't set.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response, such as network connectivity failure, DNS failure, server certificate validation error, or invalid server response. On .NET 8+, the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />.</exception>
+ <exception cref="T:System.OperationCanceledException">The request failed due to timeout.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
</Docs>
</Member>
@@ -2474,6 +2630,9 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
+ <exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" /></exception>
+ <exception cref="T:System.OperationCanceledException">The request failed due to timeout.</exception>
</Docs>
</Member>
<Member MemberName="PatchAsync">
@@ -2536,8 +2695,10 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
+ <exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" /></exception>
+ <exception cref="T:System.OperationCanceledException">The cancellation token was canceled or the request failed due to timeout.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
- <exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.</exception>
</Docs>
</Member>
<Member MemberName="PatchAsync">
@@ -2593,7 +2754,9 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
- <exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.</exception>
+ <exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" /></exception>
+ <exception cref="T:System.OperationCanceledException">The cancellation token was canceled or the request failed due to timeout.</exception>
</Docs>
</Member>
<MemberGroup MemberName="PostAsync">
@@ -2678,7 +2841,11 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
</Docs>
@@ -2739,7 +2906,11 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -2808,7 +2979,11 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
@@ -2875,7 +3050,11 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -2965,7 +3144,11 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
</Docs>
@@ -3026,7 +3209,11 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -3095,7 +3282,11 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.UriFormatException">The provided request URI is not valid relative or absolute URI.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
@@ -3162,7 +3353,11 @@ The size specified is greater than the maximum allowed buffer size.</exception>
]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The <paramref name="requestUri" /> must be an absolute URI or <see cref="P:System.Net.Http.HttpClient.BaseAddress" /> must be set.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -3218,7 +3413,7 @@ The custom class derived from <see cref="T:System.Net.Http.HttpContent" /> does
The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override the <see cref="M:System.Net.Http.HttpMessageHandler.Send(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />.</exception>
<exception cref="T:System.OperationCanceledException">If the <see cref="T:System.OperationCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
The request failed due to timeout.</exception>
</Docs>
@@ -3273,7 +3468,7 @@ The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override
The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override the <see cref="M:System.Net.Http.HttpMessageHandler.Send(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />.</exception>
<exception cref="T:System.OperationCanceledException">If the <see cref="T:System.OperationCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
The request failed due to timeout.</exception>
</Docs>
@@ -3328,7 +3523,7 @@ The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override
The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override the <see cref="M:System.Net.Http.HttpMessageHandler.Send(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -3388,7 +3583,7 @@ The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override
The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override the <see cref="M:System.Net.Http.HttpMessageHandler.Send(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -3471,7 +3666,11 @@ This method stores in the task it returns all non-usage exceptions that the meth
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -3533,7 +3732,11 @@ This method stores in the task it returns all non-usage exceptions that the meth
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">.NET Core and .NET 5 and later only: The request failed due to timeout.</exception>
</Docs>
</Member>
@@ -3595,7 +3798,11 @@ This method stores in the task it returns all non-usage exceptions that the meth
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
@@ -3663,7 +3870,11 @@ This method stores in the task it returns all non-usage exceptions that the meth
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
- <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.</exception>
+ <exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an issue getting a valid HTTP response such as network connectivity failure, DNS failure, server certificate validation error or invalid server response. On .NET 8+ the reason is indicated by <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />
+
+-or-
+
+.NET Framework only: the request timed out.</exception>
<exception cref="T:System.OperationCanceledException">The cancellation token was canceled. This exception is stored into the returned task.
-or-
diff --git a/xml/System.Net.Http/HttpResponseMessage.xml b/xml/System.Net.Http/HttpResponseMessage.xml
index 3372a83505f..c4e5b30005d 100644
--- a/xml/System.Net.Http/HttpResponseMessage.xml
+++ b/xml/System.Net.Http/HttpResponseMessage.xml
@@ -351,8 +351,10 @@ When the `disposing` parameter is `true`, this method releases all resources hel
<format type="text/markdown"><![CDATA[
## Remarks
- The <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A> method throws an exception if the HTTP response was unsuccessful. In .NET Framework and .NET Core 2.2 and earlier versions, if the <xref:System.Net.Http.HttpResponseMessage.Content%2A> is not `null`, this method will also call <xref:System.Net.Http.HttpResponseMessage.Dispose%2A> to free managed and unmanaged resources. Starting with .NET Core 3.0, the content will not be disposed.
-
+ The <xref:System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode%2A> method throws an <xref:System.Net.Http.HttpRequestException> if <xref:System.Net.Http.HttpResponseMessage.StatusCode> is outside of the range 200-299 (the range of status codes indicating success according to the standard).
+ In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if <xref:System.Net.Http.HttpResponseMessage.StatusCode> matches the expected value.
+ In .NET Framework and .NET Core 2.2 and earlier versions, if the <xref:System.Net.Http.HttpResponseMessage.Content%2A> is not `null`, this method also calls <xref:System.Net.Http.HttpResponseMessage.Dispose%2A> to free managed and unmanaged resources. Starting with .NET Core 3.0, the content is not disposed.
+
]]></format>
</remarks>
<exception cref="T:System.Net.Http.HttpRequestException">The HTTP response is unsuccessful.</exception>