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 a standard, every team reinvents it differently, risks leaking internal details to clients, and returns the wrong Content-Type.
// ❌ What you write today — 30+ lines of boilerplate per error type
The solution
// ✅ axum-problem: one attribute per variant
use AxumProblem;
use Error;
// Works directly in axum handlers
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"
}
How it maps
flowchart LR
A["Error enum variant<br/>#[error(...)] + #[problem(status = 404)]"] -->|"#[derive(AxumProblem)]"| B["IntoResponse::into_response()"]
B --> C["RFC 9457 JSON<br/>application/problem+json"]
Each variant's attributes map directly onto the RFC 9457 response fields:
// ─┐
// │
NotFound , // ─┘─▶ Display impl becomes "detail"
Attributes
Apply #[problem(...)] to each variant:
| Attribute | Required | Description |
|---|---|---|
status = <u16> |
Yes | HTTP status code. Title auto-derived from the code. |
title = "<str>" |
No | Override the default title. |
mask |
No | Hides detail from HTTP response; logs it via tracing instead. |
log = "<level>" |
No | Only relevant when mask is set. Tracing level used to log the masked error: "error" (default), "warn", "info", or "debug". |
The mask attribute — production safety
Without mask, internal errors reach clients:
{"detail": "connection to 10.0.0.5:5432 refused"} ← exposes your network
With mask:
{"title": "Internal Server Error", "status": 500} ← clean client response
ERROR error="connection to 10.0.0.5:5432 refused" status=500 ← in your logs
Combine mask with log to control the log level for errors that are expected
to happen occasionally (rate limiting, etc.) instead of always logging at error:
RateLimited,
All 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 use the enum's Display implementation — so thiserror's #[error("...")] templates apply correctly.
Manual construction
For one-off errors where a full enum is overkill:
use Problem;
not_found
.detail
.instance
Convenience constructors: bad_request(), unauthorized(), forbidden(),
not_found(), method_not_allowed(), conflict(), unprocessable_entity(),
too_many_requests(), internal_server_error(), not_implemented(),
service_unavailable().
RFC 9457 extension members
Add arbitrary top-level fields alongside the standard ones:
use json;
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). Apply ProblemLayer last
(outermost layer) so it catches errors from all other middleware and extractors.
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:
Crates in this workspace
| Crate | Description |
|---|---|
axum-problem |
Main library — Problem struct + AxumProblem re-export |
axum-problem-derive |
Proc-macro — #[derive(AxumProblem)] |
Testing
77 unit and integration tests (plus doc-tests) covering the derive macro (all
variant styles), ProblemLayer, adversarial inputs (Unicode, long strings,
10k concurrent requests), RFC 9457 compliance, and security (masking field
values, chained error sources).
Changelog
See CHANGELOG.md for release history.
License
MIT OR Apache-2.0