Generic Error Management in APIs

Axum simplifies error handling with a straightforward principle: an application should not crash when encountering an error. All errors must be considered infallible.

In essence, every error should translate into an HTTP response. Just as a JSON object can be represented as a response, we can structure our errors as objects that are appropriately served to clients, complete with the correct response codes. This post will explore two approaches to achieve this, beginning with a basic status response that utilizes string errors. To keep things simple, we will start with text responses, which can be rendered using Axum’s built-in status code error renderer.

Project Setup

We will initiate a new application for demonstration purposes:

cargo new axum-error-handling-demo

Next, we need to add the required dependencies to begin crafting our APIs. A simple handler will be included that takes a query parameter and returns it in the response. Essentially, it acts as a "Hello, World!" example with an added query parameter value. Below is the application definition that sets up this endpoint at /hello.

Solution

To address this, we can modify our struct to accept an Option<String> instead of a String parameter. This way, if no value is provided, we avoid exposing internal details in the error message.

Next, we will perform input validation to facilitate a custom error response for our clients. Here’s the updated struct:

Now, if you call the same endpoint without the query parameter, you should receive a user-friendly error message indicating what might be wrong:

http://localhost:3000/hello

This will return:

Required Parameter name is missing within the request.

JSON Error Responses

Until now, we have seen how to model errors in the Axum framework using simple strings. Since the majority of REST APIs are designed as JSON APIs, let’s explore how to format errors as JSON responses.

To represent errors in JSON, we need to define our application error models. We will create an ApiError object that serves as the root error, containing the HTTP status code and several helper methods for initializing errors. We will also leverage the thiserror library to easily create custom errors in Rust.

Translating Errors into Responses

As previously mentioned, errors are merely responses to failures within the API. They should not cause the program to crash but should inform the client about the issue in a meaningful way. When using custom structs, it is our responsibility to convert them into appropriate responses.

Fortunately, Axum simplifies this process significantly. You can view it as just another JSON response, as if the request had succeeded. Additionally, we need to ensure that the HTTP response codes are adjusted to enable clients to take necessary actions.

To allow Axum to recognize ApiError as the error response type, we will implement the IntoResponse trait for our struct. This informs Axum that it is a valid error type, and any payload within this error will be converted into an HTTP response using JSON serialization.

Below is the implementation for our ApiError struct. Here, we parse the status code related to the error and serialize our struct into a response. This approach provides users with a clear view of all errors in a neatly formatted JSON structure. Let’s implement a handler and test it out. Observe how the method signature adapts for our API.

Testing the API

We can repeat our earlier call with a valid query parameter, which should yield a new response with the expected result:

http://localhost:3000/hello?name=test

This will return:

{ "greeting": "hello", "name": "test" }

Now, let’s try it without the query parameter:

http://localhost:3000/hello

This should respond with:

{

"status_code": 400,

"errors": [

"Required Parameter name is missing within the request."

]

}

Conclusion

In this article, we explored a straightforward yet powerful method for handling errors within the Axum framework in Rust. We observed that our handler definitions have become more streamlined, and our ApiError struct ensures that responses are communicated effectively to users. Although setting up this project initially may require some effort, once established, all error handling within the application is standardized, ensuring consistency. Furthermore, the ApiError struct could be extracted into a separate crate for use across multiple Axum projects.

The first video titled "Custom Errors - Introduction to Axum 0 5" provides an overview of implementing custom error handling in the Axum framework, offering practical insights and examples.

The second video, "Stream archive: Handling errors in Axum and state management (2023-09-15)," discusses strategies for managing errors and state within Axum, highlighting best practices for developers.