Retrieving HTTP Status Code and Response with Curl

Introduction

Curl is a powerful command-line tool for transferring data with URLs. A common requirement is to obtain both the HTTP status code and the response body from a web request in one command. However, using the -I flag alone only fetches headers, leaving out the response body. This article delves into various curl options to address this issue, providing detailed code examples and explanations.

Combining -I and -o Flags

To retrieve both headers and the response body, you can use the -I flag along with -o to direct output to standard output. For example, run the following command:

curl -o - -I http://localhost

Here, -I sends a HEAD request, and -o - specifies output to stdout, which includes both headers and the potential response body. Note that some servers may not return a body for HEAD requests, so this method might not always work as expected. It is suitable for servers that support HEAD requests with full responses.

Using the -w Option for Status Code

Another approach is to use the -w (write-out) option to extract only the HTTP status code. For instance:

curl -o /dev/null -s -w "%{http_code}\n" http://localhost

This command uses -s to suppress default output, saves the response to /dev/null, and prints only the HTTP status code. This is useful in scripting, such as in automation tasks where you need to check the status without the full response, enabling seamless integration into error handling workflows.

Verbose Mode for Detailed Output

The verbose mode with -v provides comprehensive details, including headers and the response body. Run:

curl -v http://localhost

This outputs information to stderr, showing the entire request and response process, including status codes and bodies. Although the output is verbose, it can be parsed to extract needed information, making it ideal for debugging and in-depth analysis.

Advanced Error Handling with Scripts

For robust error handling, you can capture the status code and response separately. Based on the Q&A data, use the following command:

http_response=$(curl -s -o response.txt -w "%{http_code}" http://example.com)

Then, in a shell script, check the status code:

if [ "$http_response" -eq 200 ]; then
    echo "Server returned success:"
    cat response.txt
else
    echo "Error: HTTP $http_response"
fi

This method allows conditional processing based on the HTTP status, such as in webhook integrations (as referenced in Article 2), ensuring appropriate responses in case of errors. By combining with redirect handling (e.g., using -L flag to follow redirects), it can manage complex HTTP scenarios like 301 redirects to 200 status.

Practical Applications and Examples

In real-world applications, such as webhook error handling (Reference Article 2), correctly parsing HTTP responses is crucial. Using curl's -FOLLOWLOCATION option can automatically handle redirects:

curl -L http://example.com

This command follows all redirects and returns the final response, facilitating the handling of multi-step HTTP interactions in scripts. Combined with status code checks, it enables the building of reliable automation flows, reducing manual intervention.

Conclusion

Curl offers multiple flexible ways to retrieve HTTP status codes and response bodies. By effectively using options like -I, -o, -w, and -v, users can tailor commands to their needs, enhancing script efficiency and reliability. Mastering these techniques helps optimize HTTP request processing in web development, system administration, and automation tasks.