Can I make cURL fail with an exitCode different than 0 if the HTTP status code is not 200?

Question

I was always assuming that when curl got an HTTP 500 response it was returning an exit code that meant failure (!= 0), but that seems to be not the case.

Is there a way I can I make cURL fail with an exitCode different than 0 if the HTTP status code is not 200? I know I can use -w "%{http_code}" but that puts it in STDOUT, not as the exit code (besides, I'm also interested in capturing the output, which I don't want to redirect to a file, but to the screen).

score 581 · Answer 1 · edited Jun 12 '20 at 13:48

curl --fail does part of what you want:

from man curl:

-f, --fail

(HTTP) Fail silently (no output at all) on server errors. This is mostly done to better enable scripts etc 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 flag will prevent curl from outputting that and return error 22.

This method is not fail-safe and there are occasions where non-successful response codes will slip through, especially when authentication is involved (response codes 401 and 407).

But it blocks output to the screen.

phemmer · Answer 2 · 2023-02-15T14:04:10.080

Use --fail-with-body. This will cause curl to exit with status code 22 when response code is >=400.

Note though that this flag is brand new ^{(as of 2021/02/15)}, and was added in version 7.76.0, which postdates @rampion's answer. Thus it might not be available on your system.

https://curl.se/docs/manpage.html

--fail-with-body

(HTTP) Return an error on server errors where the HTTP response code is 400 or greater). 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 flag will still allow curl to outputting and save that content but also to return error 22.

This is an alternative option to -f, --fail which makes curl fail for the same circumstances but without saving the content.

See also -f, --fail. Added in 7.76.0.

-f, --fail

(HTTP) Fail silently (no output at all) on server errors. This is mostly done to enable scripts etc 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 flag will prevent curl from outputting that and return error 22.

This method is not fail-safe and there are occasions where non-successful response codes will slip through, especially when authentication is involved (response codes 401 and 407).

See also --fail-with-body.

score 141 · Answer 3 · edited Apr 07 '22 at 14:36

141

If you just want to display the contents of the curled page, you can do this:

STATUSCODE=$(curl --silent --output /dev/stderr --write-out "%{http_code}" URL)
if test $STATUSCODE -ne 200; then
    # error handling
fi

This writes the page's content to STDERR while writing the HTTP status code to STDOUT, so it can be assigned to the variable STATUSCODE.

edited Apr 07 '22 at 14:36

Itay Grudev

371
1
3
16

answered May 01 '13 at 15:31

Dennis

50,701

score 104 · Accepted Answer · edited Dec 09 '21 at 16:11

Most of the answers provided so far will not print the HTTP response body in case an HTTP request fails.

If you would like to print the response body as well, even if the exit code is non-zero due to the HTTP request failing: provided you have curl v7.76 or newer, simply use curl --fail-with-body.

For older versions of curl, try this:

curlf() {
  OUTPUT_FILE=$(mktemp)
  HTTP_CODE=$(curl --silent --output $OUTPUT_FILE --write-out "%{http_code}" "$@")
  if [[ ${HTTP_CODE} -lt 200 || ${HTTP_CODE} -gt 299 ]] ; then
    >&2 cat $OUTPUT_FILE
    return 22
  fi
  cat $OUTPUT_FILE
  rm $OUTPUT_FILE
}

score 102 · Answer 5 · edited Jul 21 '21 at 09:40

102

I was able to do it using a combination of flags:

curl --silent --show-error --fail URL

--silent hides the progress and error
--show-error shows the error message hidden by --silent
--fail returns an exit code > 0 when the request fails

edited Jul 21 '21 at 09:40

phuclv

30,396
15
136
260

answered Sep 12 '17 at 14:48

Ricardo Souza

1,181

score 16 · Answer 6 · answered Sep 23 '20 at 08:22

16

I ended up with this based on Dennis's answer, a quick one-liner that fails for non-200 status codes while retaining the output (to stderr):

[ $(curl ... -o /dev/stderr -w "%{http_code}") -eq 200 ]

answered Sep 23 '20 at 08:22

shesek

261

score 13 · Answer 7 · answered Sep 04 '19 at 13:25

Yes there is a way to do it but is far from obvious as it involves 3 curl options:

curl -s --fail --show-error https://httpbin.org/status/200 > /dev/null
curl -s --fail --show-error https://httpbin.org/status/401 > /dev/null
curl -s --fail --show-error https://httpbin.org/status/404 > /dev/null
curl -s --fail --show-error https://bleah-some-wrong-host > /dev/null

This assures that success (0) happens only when curl end-us with final 2xx return code and that stdout gets the body and that any errors would be displayed to stderr.

Please note that curl documentation may confuse you a little bit because it mentions that --fail could succeed for some 401 codes. Based on tests that is not true, at least not when used with --show-error at the same time.

So far I was unable to find any case where curl will return success when it was not a http-succeds with these options.

score 4 · Answer 8 · edited Jul 21 '21 at 09:39

I recently also needed something like this but I also wanted to print the output at all times. I used the http_code extraction and grep to achieve this.

out=$(curl -H"Content-Type: application/json"  -w '\nstatus_code=%{http_code}\n' -s http://localhost:4040${uri} -d "${body}")
code=$(echo ${out}|grep status_code|awk -F"=" '{print $2}')
echo ${out}
if [[ ${code} -ge 400 ]];
then
    exit 2;
fi;

t0r0X · Answer 9 · 2021-04-14T08:53:24.397

This is based on @Dennis's solution, but shows the output only on error (return code not 200):

#!/bin/bash
Create temp file, readable and writable only by current user and root
SCRATCH=$( umask 0077; mktemp -t tmp.XXXXXXXXXX )
Cleanup temp file on script exit
function cleanup_on_exit {
    rm -f "$SCRATCH"
}
trap cleanup_on_exit EXIT
Perform curl call
HTTP_CODE=$( curl -s -o "$SCRATCH" -w '%{http_code}' your..stuff..here )
Analyze HTTP return code
if [ ${HTTP_CODE} -ne 200 ] ; then
    cat "${SCRATCH}"
    exit 1
fi

Alternative HTTP return code handling, where 2XX is OK:

# Analyze HTTP return code
if [ ${HTTP_CODE} -lt 200 ] || [ ${HTTP_CODE} -gt 299 ] ; then
    cat "${SCRATCH}"
    exit 1
fi

score 2 · Answer 10 · answered Jul 31 '21 at 23:49

Here was my solution - it uses jq and assumes the body is json

#  this code adds a statusCode field to the json it receives and then jq squeezes them together
# curl 7.76.0 will have curl --fail-with-body and thus eliminate all this
  local result
  result=$(
    curl -sL -w ' { "statusCode": %{http_code}} ' -X POST "${headers[@]}" "${endpoint}" \
      -d "${body}"  "$curl_opts" | jq -ren '[inputs] | add'
  )
#   always output the result
  echo "${result}"
#  jq -e will produce an error code if the expression result is false or null - thus resulting in a
# error return code from this function naturally. This is much preferred rather than assume/hardcode
# the existence of a error object in the body payload
  echo "${result}" | jq -re '.statusCode >= 200 and .statusCode < 300' > /dev/null

score 1 · Answer 11 · answered Jun 28 '21 at 21:34

I recently tried to use the approaches shown here but kept having an error because curl was providing the response_code as 000401 when it should be 401 (curl 7.64.1 (x86_64-apple-darwin19.0). Bash converts 000401 to 257 so trying to test for >=200 and <=299 wasn't reliable.

I end up with this function:

function curl_custom() {
    local RESPONSE_CODE
    RESPONSE_CODE=$(curl -v --silent --output /dev/stderr --write-out "%{response_code}" "$@")
# Remove leading zeros (if any) to prevent bash interpreting result as octal
RESPONSE_CODE=${RESPONSE_CODE##+(0)}

if (( RESPONSE_CODE &gt;= 200 )) &amp;&amp; (( RESPONSE_CODE &lt;= 299 )) ; then
    echo &quot;INFO - Got response ${RESPONSE_CODE}&quot;
else
    echo &quot;ERROR - Request failed with ${RESPONSE_CODE}&quot;
    return 127
fi

}

Examples on usage:

curl_custom example.com example.com
curl_custom -X PUT -U user:pass file.json example.com/api

Hope it helps.

score 0 · Answer 12 · answered Mar 09 '24 at 18:59

to also write the error body to stderr, parse the response headers in bash, and then, depending on the response status, send the response body to stdout (cat) or to stderr (cat >&2)

curl -s --fail-with-body -D - -o - https://httpbin.dev/status/418 | {
  status=
  while read -r header; do
    header="${header:0: -1}" # strip trailing "\r"
    #echo "header: ${header@Q}" >&2 # debug
    if [ -z "$status" ]; then
      status=${header#* } # first header has status
      status=${status%% *}
      continue
    fi
    [ -z "$header" ] && break # end of headers
  done
  #echo "status: $status" >&2 # debug
  if [ "${status:0:1}" = 2 ]; then
    cat # write body to stdout
  else
    cat >&2 # write body to stderr
  fi
} |
cat >/dev/null

this will parse the response status from the first header line, for example HTTP/2 200 or HTTP/1.1 400 OK

score 0 · Answer 13 · answered Mar 12 '25 at 11:39

Simplest solution I found is to allow redirects but only 0 times:

curl --fail --location --max-redirs 0 https://httpbin.org/status/301; echo $?
curl: (47) Maximum (0) redirects followed
47
curl --fail --max-redirs 0 https://httpbin.org/status/404; echo $?
curl: (22) The requested URL returned error: 404
22
curl --fail --location --max-redirs 0 https://httpbin.org/status/200; echo $?
0

My cURL version is 8.9.1, but those options exists for years.

Can I make cURL fail with an exitCode different than 0 if the HTTP status code is not 200?

13 Answers13

--fail-with-body

-f, --fail

Create temp file, readable and writable only by current user and root

Cleanup temp file on script exit

Perform curl call

Analyze HTTP return code

Linked