Introduction to Error Handling in API Requests Using C++

Welcome to the first lesson of Efficient API Interactions with C++. In this course, you will learn how to handle common scenarios when working with APIs more effectively. One of the key aspects of working with APIs is error handling. Handling errors gracefully is crucial for building robust applications and enhancing the user experience by providing meaningful feedback when things go wrong. Our goal in this lesson is to help you manage these outcomes effectively using C++ and the httplib library.

When you send a request to an API, the server responds with an HTTP status code. These codes indicate the outcome of your request. Understanding them is essential for effective error handling. Here's a brief overview:

• 2xx (Success): Indicates that the request was successfully received, understood, and accepted. For example, a 200 status code means OK.
• 3xx (Redirection): Indicates that further action needs to be taken by the client to complete the request. For example, a 301 Moved Permanently status code means the requested resource is now located at a different URI, and the client should use the new URL in future requests.
• 4xx (Client Errors): Suggests that there was an error in the request made by your client. For example, 404 means the requested resource was not found.
• 5xx (Server Errors): Indicates that the server failed to fulfill a valid request. A common code here is 500, which means an internal server error.

By paying attention to these codes, you can determine whether your request succeeded or if there was a problem that needs addressing.

C++'s httplib library does not provide automatic status code checks. Therefore, it's essential to manually inspect the status codes and handle errors using C++ exception handling to simplify error detection. This involves checking for 4xx and 5xx status codes and throwing exceptions as needed.

Consider the following example, which fetches todo items from an API:

#include <iostream>
#include "httplib.h"

// Base URL for the API
const std::string base_url = "http://localhost:8000";

int main() {
    // Create an HTTP client
    httplib::Client cli(base_url.c_str());

    try {
        // Send a GET request to the /todos endpoint
        auto res = cli.Get("/todos");

        // Check if the response is valid
        if (!res) {
            throw std::runtime_error("Request failed: No response from server");
        }

        // Check if the response has a 4xx or 5xx status code
        if (res->status >= 400) {
            throw std::runtime_error("HTTP error occurred: " + std::to_string(res->status));
        }
        
        // If no exception was raised, print success message
        std::cout << "Todos fetched successfully!" << std::endl;
        std::cout << "Response: " << res->body << std::endl;

    } catch (const std::exception &e) {
        // Handle any exceptions
        std::cerr << "Error occurred: " << e.what() << std::endl;
    }

    return 0;
}

In this example, the status code is manually checked to detect HTTP errors by throwing exceptions when 4xx or 5xx status codes are encountered. Such an approach allows for explicit and precise error handling, ensuring that any issues are properly reported and managed.

The res object will be nullptr if the request fails before the server responds. This can happen due to:

• No internet connection or incorrect API URL
• The API server is down or unreachable
• A timeout occurs before the request completes
• SSL/TLS verification issues (if using HTTPS and there's a certificate problem)

Checking if (!res) ensures that we handle these cases before even inspecting the HTTP status code.

Following our discussion on handling unsuccessful status codes, let's delve into scenarios where errors might occur. In this example, a GET request is sent to a non-existent route, leading to an HTTP error because a 404 Not Found status code is returned.

try {
    // Attempt to fetch from a non-existent endpoint
    if (auto res = cli.Get("/invalid-route")) {
        if (res->status == 404) {
            throw std::runtime_error("HTTP error occurred: 404 Not Found");
        }
    } else {
        throw std::runtime_error("Request error: Could not connect to server");
    }
} catch (const std::exception &e) {
    std::cerr << e.what() << std::endl;
}

This will produce the following error message indicating that the requested resource was not found:

HTTP error occurred: 404 Not Found

Continuing with error handling, the next scenario involves sending a POST request without a required field, the title, resulting in an HTTP error due to a 400 Bad Request.

try {
    // Sending a POST request without the 'title' in the payload using JSON
    nlohmann::json newTodo;  // Empty payload
    auto res = cli.Post("/todos", newTodo.dump(), "application/json");

    if (res) {
        if (res->status == 400) {
            throw std::runtime_error("HTTP error occurred: 400 Bad Request");
        }
    } else {
        throw std::runtime_error("Request error: Could not connect to server");
    }
} catch (const std::exception &e) {
    std::cerr << e.what() << std::endl;
}

The condition if (res) ensures that we have received a valid response before attempting to access res->status. If the request fails due to a connectivity issue, res will be nullptr, and trying to access res->status without this check would result in undefined behavior or a crash.

The following error message informs us of a 400 Bad Request error, indicating missing required fields.

HTTP error occurred: 400 Bad Request

Finally, let's examine how to handle broader request-related issues. This example demonstrates a scenario where an error occurs due to connectivity issues or other problems external to the HTTP response itself.

try {
    // Attempt to fetch todos while expecting a connectivity issue or similar error
    httplib::Client invalid_cli("http://invalid-url");
    if (auto res = invalid_cli.Get("/")) {
        // Normally handle response here
    } else {
        throw std::runtime_error("Request error: Could not connect to server");
    }
} catch (const std::exception &e) {
    std::cerr << e.what() << std::endl;
}

The following output shows a 400 Bad Request error, indicating missing required fields:

Request error: Could not connect to server

In this lesson, you learned about the importance of error handling in API requests and were introduced to effective techniques using HTTP status codes, manual status checking, and exception handling with C++. These practices are crucial for creating robust applications that deal with errors gracefully and provide clear feedback to users.

You are now equipped to practice these skills through hands-on exercises that will reinforce the concepts you've learned. As you move forward, you'll continue to build on these techniques to engage with more advanced API features. Remember, practicing error handling is key — experiment with different scenarios to see how errors are managed and how they affect your applications.