curl --fail-with-body: Fail but Keep the Error Body
Plain --fail hides the body on error, which throws away the message you need to debug.
When an API returns a structured JSON error, you want both a failing exit code and the body. --fail-with-body gives you both.
What it does
--fail-with-body makes curl exit non-zero on HTTP responses 400 and above, the same as --fail, but it does not suppress the response body. The error JSON or HTML still reaches stdout so it shows up in your logs. It was added in curl 7.76.0.
Common usage
curl --fail-with-body -sS https://api.example.com/deploy
# capture the error body and the status
curl --fail-with-body -sS -o resp.json -w '%{http_code}' https://api.example.com/xFlags
| Flag | What it does |
|---|---|
| --fail-with-body | Exit non-zero on >= 400, still print the body (curl 7.76+) |
| -f / --fail | Exit 22 on >= 400 but discard the body |
| -o <file> | Write the body to a file even on error |
| -sS | Silence the progress meter but keep error text |
In CI
Reach for --fail-with-body when the API returns a meaningful error payload, for example a validation message. You get a failing step and the reason in one shot. If your runner image ships an older curl, --fail-with-body is unknown; check with curl --version and fall back to -f.
Common errors in CI
curl: option --fail-with-body: is unknown means the curl on the runner predates 7.76. Either upgrade curl or use -f and accept losing the body. curl: (22) ... returned error: 400 with the body still printed is the expected behavior.