cmdline-opts/fail.md: expand and clarify

Closes #13890

diff --git a/docs/cmdline-opts/fail.md b/docs/cmdline-opts/fail.md
index 8591e330db498445ff0cf91d14f572e6db576581..0c8db1367b5434869f2682b82627dbc462e00285 100644 (file)
--- a/docs/cmdline-opts/fail.md
+++ b/docs/cmdline-opts/fail.md
@@ -18,11 +18,17 @@ Example:
 
 # `--fail`
 
-Fail fast with no output at all on server errors. This is useful to enable
-scripts and users to better deal with failed attempts. In normal cases when an
-HTTP server fails to deliver a document, it returns an HTML document stating
-so (which often also describes why and more). This command line option
-prevents curl from outputting that and return error 22.
+Fail with error code 22 and with no response body output at all for HTTP
+transfers returning HTTP response codes at 400 or greater.
+
+In normal cases when an HTTP server fails to deliver a document, it returns a
+body of text stating so (which often also describes why and more) and a 4xx
+HTTP response code. This command line option prevents curl from outputting
+that data and instead returns error 22 early. By default, curl does not
+consider HTTP response codes to indicate failure.
+
+To get both the error code and also save the content, use --fail-with-body
+instead.
 
 This method is not fail-safe and there are occasions where non-successful
 response codes slip through, especially when authentication is involved