curl Returns Exit Code 0 on HTTP 404: Fix CI Failure Checks

Choose the HTTP failure behavior#

The curl manual documents --fail-with-body for HTTP responses with status 400 or greater. It returns error 22 while keeping the response body. The option was added in curl 7.76.0; check curl --version on the runner, rather than assuming your laptop and CI have the same version.

Do not combine --fail and --fail-with-body: the options are mutually exclusive. If an older runner cannot use --fail-with-body, --fail provides the HTTP failure check for this case, but loses the server’s diagnostic body. The manual also warns that --fail has authentication-related exceptions; do not treat this 404 demonstration as exhaustive testing of every HTTP exchange.

Reproduce both failure layers locally#

The following fixture needs Python 3, curl 7.76.0 or newer, and Bash. It starts an HTTP server on an automatically selected loopback port and always returns a small JSON body with HTTP 404. No public endpoint, credential, or deployment is required.

Run it from a terminal:

1
python3 - <<'PY'
2
from http.server import BaseHTTPRequestHandler, HTTPServer
3
from threading import Thread
4
import os
5
import subprocess
6

7
class Handler(BaseHTTPRequestHandler):
8
    def do_GET(self):
9
        body = b'{"error":"missing"}\n'
10
        self.send_response(404)
11
        self.send_header('Content-Type', 'application/json')
12
        self.send_header('Content-Length', str(len(body)))
13
        self.end_headers()
14
        self.wfile.write(body)
15

16
    def log_message(self, *args):
17
        pass
18

19
server = HTTPServer(('127.0.0.1', 0), Handler)
20
Thread(target=server.serve_forever, daemon=True).start()
21
env = dict(os.environ, URL=f'http://127.0.0.1:{server.server_port}/missing')
22
checks = [
23
    ('plain', 'curl -q -sS "$URL"'),
24
    ('fail', 'curl -q -sS --fail "$URL"'),
25
    ('fail-with-body', 'curl -q -sS --fail-with-body "$URL"'),
26
    ('pipeline without pipefail',
27
     'set +o pipefail; curl -q -sS --fail-with-body "$URL" | cat'),
28
    ('pipeline with pipefail',
29
     'set -o pipefail; curl -q -sS --fail-with-body "$URL" | cat'),
30
    ('pipefail without HTTP failure check',
31
     'set -o pipefail; curl -q -sS "$URL" | cat'),
32
]
33
try:
34
    for label, command in checks:
35
        result = subprocess.run(['bash', '-c', command], env=env,
36
                                capture_output=True, text=True)
37
        print(f'{label}: exit={result.returncode}, body={result.stdout.strip()!r}')
38
finally:
39
    server.shutdown()
40
    server.server_close()
41
PY

The fixture was executed during preparation on macOS with curl 8.7.1 and Bash 3.2.57 on October 4, 2026. Its output was:

1
plain: exit=0, body='{"error":"missing"}'
2
fail: exit=22, body=''
3
fail-with-body: exit=22, body='{"error":"missing"}'
4
pipeline without pipefail: exit=0, body='{"error":"missing"}'
5
pipeline with pipefail: exit=22, body='{"error":"missing"}'
6
pipefail without HTTP failure check: exit=0, body='{"error":"missing"}'

The fixture captures stderr separately, so curl’s error messages are absent from this printed output. -q is deliberately the first curl option to skip the default curl configuration file; -sS removes progress output while keeping error messages enabled.

For the fourth check, curl fails but cat successfully reads the error body. Bash normally uses the last command’s status for a pipeline, so the pipeline returns 0. With pipefail, Bash instead returns the rightmost nonzero status, which is curl’s 22 in this example. This is the behavior defined in the Bash pipeline reference.

Preserve the failure in a CI script#

For a single request, an explicit conditional avoids depending on implicit shell exit behavior. This Bash pattern saves the response for inspection and exits with curl’s status on failure:

1
#!/usr/bin/env bash
2
url='https://api.example.com/health' # Replace with your endpoint.
3

4
if curl -q --silent --show-error --fail-with-body \
5
  --connect-timeout 10 --max-time 30 \
6
  --output response.json "$url"; then
7
  printf 'HTTP request completed without a curl failure.\n'
8
else
9
  rc=$?
10
  printf 'curl failed with exit code %s\n' "$rc" >&2
11
  # Inspect response.json only where its contents may be disclosed.
12
  exit "$rc"
13
fi

The local 404 fixture also verified the conditional’s failure branch and saved JSON body. The public endpoint above is illustrative and was not called. response.json may contain sensitive error details; writing it to disk does not automatically make it suitable for CI logs or uploaded artifacts. If you intentionally upload that file, account for your workflow’s artifact file selection.

Capture $? immediately in the else branch. Avoid if ! curl ...; then rc=$?: the ! has already inverted the status, so that assignment does not preserve the original curl failure.

If your real command pipes curl into another program, enable pipefail in the Bash process that runs the pipeline and explicitly return its failure:

1
set -o pipefail
2
if curl -q -sS --fail-with-body "$url" | cat; then
3
  printf 'Pipeline completed without a failure.\n'
4
else
5
  rc=$?
6
  exit "$rc"
7
fi

cat isolates the shell behavior here; replace it with your actual consumer only after checking that program’s exit behavior. pipefail changes the pipeline’s status, not whether downstream commands run. It does not validate the JSON body or stop a consumer from processing an error response.

Define what counts as success#

These examples prove the HTTP 404 boundary, not an application health guarantee. A response can be valid HTTP yet contain an application error. Likewise, the documented HTTP failure threshold does not assert that a redirect or every non-200 status should fail your particular check.

If your contract requires exactly HTTP 200, a specific JSON field, or a final destination after redirects, add and verify that condition separately. For the narrower problem shown here, use the HTTP failure flag first, then verify the standalone command, pipeline, and final script exit status against a deliberately failing endpoint.

References:

• curl FAQ: HTTP error responses and curl failures
• curl manual: —fail-with-body
• GNU Bash manual: pipelines