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).

Answer 1

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.

Answer 2

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.

Answer 3

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.

Answer 4

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

Answer 5

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
}

Answer 6

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.

Answer 7

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 ]

Answer 8

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;

Answer 9

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

Answer 10

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

Answer 11

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 >= 200 )) && (( RESPONSE_CODE <= 299 )) ; then
        echo "INFO - Got response ${RESPONSE_CODE}"
    else
        echo "ERROR - Request failed with ${RESPONSE_CODE}"
        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.