axum-problem
RFC 9457 problem details for axum — #[derive(AxumProblem)] converts your error enums to structured HTTP error responses with one attribute.
[]
= "0.1"
= "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
The solution
// ✅ axum-problem: one attribute per variant, derive does the rest
use AxumProblem;
use Error;
// Works directly in axum handlers — no extra code
async
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:
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.
Database,
// 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:
Manual construction
For one-off errors where a full enum is overkill:
use Problem;
use json;
async
Convenience constructors: bad_request(), unauthorized(), forbidden(),
not_found(), conflict(), unprocessable_entity(), too_many_requests(),
internal_server_error(), service_unavailable().
RFC 9457 extension members
Add arbitrary top-level fields alongside the standard ones:
new
.detail
.extension
.extension
Produces:
Extension fields are serialized flat at the top level — not nested under an
"extensions" key — as RFC 9457 §3.5 requires.
ProblemLayer — catch axum's own errors
axum's built-in extractors (bad JSON body, wrong Content-Type, missing fields)
return plain text errors, not application/problem+json. ProblemLayer fixes
this by intercepting any 4xx/5xx response that isn't already a problem response:
use Router;
use ProblemLayer;
let app = new
/* ... your routes ... */
.layer;
Now every error — including axum extractor failures — returns structured
application/problem+json. Responses already in problem+json format pass
through unchanged (extension fields preserved).
utoipa / OpenAPI integration
Enable the utoipa feature to expose Problem in your OpenAPI spec:
[]
= { = "0.1", = ["utoipa"] }
= "4"
Problem implements ToSchema — use it directly in #[utoipa::path] responses:
async
The generated schema includes all RFC 9457 standard fields plus
additionalProperties: true to represent extension members.
Works without thiserror
AxumProblem only requires Display — you can use it with any error type:
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