This exists to encapsulate a number of common patterns when returning errors from Axum routes. These patterns include:

• wanting to return error responses as a JSON object
• to automatically convert errors raised in the route hander into that standardised JSON response
• provide appropriate default error messages for public use, which takes into account the status code in use
• a need to optionally add extra data to the error JSON output

A basic tutorial

Below is a mock example route to download a User object:

use ::axum::extract::State;
use ::axum_route_error::RouteError;
use ::sea_orm::DatabaseConnection;

pub async fn route_get_user(
    State(ref db): State<DatabaseConnection>,
    Path(username): Path<String>
) -> Result<ExampleUser, RouteError> {
    // If this errors, then a `RouteError::new_internal_server()` is returned.
    let user = get_user_from_database(db, &username).await?;

    Ok(user)
}

If the get_user_from_database function returns an error, then the handler will return a Response. The Response will have a 500 status code (for an internal error), and return the following output:

{
  "error": "An unexpected error occurred"
}

Different RouteError types

Let's presume get_user_from_database returns a Result<Option, Error>. We want to return a 500 if it returns an error (like above), and change the code to return a 404 if the user is not found.

use ::axum::extract::State;
use ::axum_route_error::RouteError;
use ::sea_orm::DatabaseConnection;

pub async fn route_get_user(
    State(ref db): State<DatabaseConnection>,
    Path(username): Path<String>
) -> Result<ExampleUser, RouteError> {
    let user = get_user_from_database(db, &username).await?
      // This additional line will return a 404 if the user is not found.
      .ok_or_else(|| RouteError::new_not_found())?;

    Ok(user)
}

If the user is not found (get_user_from_database returns None), then this will return a 404 Response with the following JSON:

{
  "error": "The resource was not found"
}

Adding additional error data

Next let's add extra information to the error. Something more than just an error message.

This can be done by making a new type that serializes using Serde, and then adding this to the RouteError.

use ::axum::extract::State;
use ::axum_route_error::RouteError;
use ::sea_orm::DatabaseConnection;
use ::serde::Deserialize;
use ::serde::Serialize;

// The additional error information needs to derive these three traits.
#[derive(Deserialize, Serialize, Debug)]
pub struct UserErrorInformation {
  pub username: String
}

pub async fn route_get_user(
    State(ref db): State<DatabaseConnection>,
    Path(username): Path<String>
// The `RouteError` needs the additional data marked here
) -> Result<ExampleUser, RouteError<UserErrorInformation>> {
    let user = get_user_from_database(db, &username).await?
      .ok_or_else(move || {
        // Then you can add the data through method chaining
        RouteError::new_not_found()
          .set_error_data(UserErrorInformation {
            username,
          })
      })?;

    Ok(user)
}

If the user is not found (get_user_from_database returns None), then this will return a 404 Response with the following JSON:

{
  "error": "The resource was not found",
  "username": "<the-username>"
}

Making Internal Errors public

Sometimes you want to make internal errors public, such as for internal services.

For this you can use the RouteInternalError. It's identical, but adds adds internal_error information to the response.