retry-all-errors.d: Explain curl errors versus HTTP response errors

- Add a paragraph explaining that curl does not consider HTTP response
  errors as curl errors, and how that behavior can be modified by using
  --retry and --fail.

The --retry-all-errors doc says "Retry on any error" which some users
may find misleading without the added explanation.

Ref: https://curl.se/docs/faq.html#Why_do_I_get_downloaded_data_eve
Ref: https://curl.se/docs/faq.html#curl_doesn_t_return_error_for_HT

Reported-by: Lawrence Gripper
Fixes https://github.com/curl/curl/issues/6712
Closes https://github.com/curl/curl/pull/6720

diff --git a/docs/cmdline-opts/retry-all-errors.d b/docs/cmdline-opts/retry-all-errors.d
index 6bda52b6e103b63b7433176de526f53f5dd9241e..5ad1da0dec31a8ba14a2209fe2b5b05a5c355e21 100644 (file)
--- a/docs/cmdline-opts/retry-all-errors.d
+++ b/docs/cmdline-opts/retry-all-errors.d
@@ -18,3 +18,11 @@ from a failed partial transfer that was written to an output file. However this
 is not true of data redirected to a | pipe or > file, which are not reset. We
 strongly suggest don't parse or record output via redirect in combination with
 this option, since you may receive duplicate data.
+
+By default curl will not error on an HTTP response code that indicates an HTTP
+error, if the transfer was successful. For example, if a server replies 404
+Not Found and the reply is fully received then that is not an error. When
+--retry is used then curl will retry on some HTTP response codes that indicate
+transient HTTP errors, but that does not include most 4xx response codes such
+as 404. If you want to retry on all response codes that indicate HTTP errors
+(4xx and 5xx) then combine with --fail.