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

1 files changed, 8 insertions, 0 deletions

diff --git a/docs/cmdline-opts/retry-all-errors.d b/docs/cmdline-opts/retry-all-errors.d
index 6bda52b6e..5ad1da0de 100644
--- 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.