axum-problem 0.1.2

RFC 9457 problem details for axum — #[derive(AxumProblem)] converts your error enums to structured HTTP error responses
Documentation

axum-problem

RFC 9457 problem details for axum — #[derive(AxumProblem)] converts your error enums to structured HTTP error responses with one attribute.

[dependencies]
axum-problem = "0.1"
thiserror = "2"     # optional but recommended

The problem

Every axum app needs structured error responses. Without this, you write 30+ lines of boilerplate per error type, risk exposing internal details to clients, and return the wrong Content-Type.

// ❌ What you write today — manually for every error enum
impl IntoResponse for ApiError {
    fn into_response(self) -> Response {
        match self {
            Self::NotFound { id } => (StatusCode::NOT_FOUND, Json(json!({"error": "not found"}))).into_response(),
            Self::Database(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(json!({"error": "internal"}))).into_response(),
            // ...
        }
    }
}

The solution

// ✅ axum-problem: one attribute per variant, derive does the rest
use axum_problem::AxumProblem;
use thiserror::Error;

#[derive(Debug, Error, AxumProblem)]
pub enum ApiError {
    #[error("order {id} not found")]
    #[problem(status = 404)]
    NotFound { id: i64 },

    #[error("access denied")]
    #[problem(status = 401)]
    Unauthorized,

    #[error("db error: {0}")]
    #[problem(status = 500, mask)]   // ← hides internal details from clients
    Database(String),
}

// Works directly in axum handlers — no extra code
async fn get_order(Path(id): Path<i64>) -> Result<Json<Order>, ApiError> {
    db.find(id).await.map(Json).map_err(ApiError::Database)
}

HTTP response from ApiError::NotFound { id: 1001 }:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "title": "Not Found",
  "status": 404,
  "detail": "order 1001 not found"
}

Attributes

status = <u16> (required)

The HTTP status code for this variant. Auto-derives the title from the status code.

title = "<str>" (optional)

Override the default title:

#[problem(status = 409, title = "Email Already Registered")]
EmailConflict,

mask (optional)

The safety attribute. Hides the error detail from the HTTP response and logs it via tracing::error! instead.

Use for any variant that could expose internal information — database errors, upstream service errors, file paths, etc.

#[error("db: {0}")]
#[problem(status = 500, mask)]
Database(sqlx::Error),
// Client receives:  {"title": "Internal Server Error", "status": 500}
// Your logs receive: ERROR error="connection refused" status=500

What the response looks like

All variants produce Content-Type: application/problem+json per RFC 9457:

{
  "type": "about:blank",        // only if problem_type() is set
  "title": "Not Found",         // from status code or custom title
  "status": 404,
  "detail": "order 1001 not found",   // absent when mask is set
  "instance": "/orders/1001"          // only if instance() is set
}

Manual construction

For one-off errors where a full enum is overkill:

use axum_problem::Problem;

async fn handler() -> impl IntoResponse {
    Problem::not_found()
        .detail("The requested resource does not exist")
        .instance("/orders/1001")
}

Convenience constructors: bad_request(), unauthorized(), forbidden(), not_found(), conflict(), unprocessable_entity(), too_many_requests(), internal_server_error(), service_unavailable().


Works without thiserror

AxumProblem only requires Display — you can use it with any error type:

#[derive(Debug, AxumProblem)]
enum MyError {
    #[problem(status = 503)]
    Down,
}

impl std::fmt::Display for MyError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "service is temporarily unavailable")
    }
}
impl std::error::Error for MyError {}

Variant types supported

Variant style Example Detail source
Unit Unauthorized Enum's Display
Struct (named fields) NotFound { id: i64 } Enum's Display
Tuple (1 field) Database(String) Enum's Display
Tuple (multiple fields) RateLimit(u32, u32) Enum's Display
Any + mask Database(String) Suppressed; logged via tracing

All variants display using the enum's Display implementation — so thiserror's #[error("...")] templates apply correctly.


License

MIT OR Apache-2.0