Skip to content

Problem details

ProblemDetails: an RFC 9457 problem document built inline, its constructors, the code each status carries, and its builders.

A glue route that doesn’t own a feature error enum can still emit a structured error body conforming to RFC 9457 — Problem Details for HTTP APIs:

crates/features/src/posts/http/controller.rs
use nest_rs::http::{Json, Opaque, Path, ProblemDetails, Result};
use uuid::Uuid;
#[get("/posts/{id}")]
async fn show(&self, Path(id): Path<Uuid>) -> Result<Json<Post>> {
let post = self.svc.find(id).await.opaque()?.ok_or_else(|| {
ProblemDetails::not_found()
.with_detail(format!("post {id} does not exist"))
.with_instance(format!("/posts/{id}"))
})?;
Ok(Json(post))
}

The lookup’s own failure goes through .opaque(): its message is the operator’s, never the client’s.

Constructors cover the well-known statuses — bad_request, unauthorized, forbidden, not_found, conflict, unprocessable, internal — and from_status any other. Each is type: "about:blank" with the status’s phrase as its title: RFC 9457’s spelling of a problem that says nothing beyond its status, the one every problem the framework renders carries. A status that names one of the framework’s classes adds that class’s code: the code a Problem of that class carries on every edge, so a #[crud] refusal, a guard’s denial or a failure the client is not told of reads here as it does on GraphQL, WebSockets and MCP:

Statuscode
400, 422INVALID_ARGUMENT
401UNAUTHENTICATED
403FORBIDDEN
404NOT_FOUND
405METHOD_NOT_ALLOWED
406NOT_ACCEPTABLE
408REQUEST_TIMEOUT
409CONFLICT
410GONE
412PRECONDITION_FAILED
413CONTENT_TOO_LARGE
415UNSUPPORTED_MEDIA_TYPE
416RANGE_NOT_SATISFIABLE
426UPGRADE_REQUIRED
429RATE_LIMITED
503UNAVAILABLE
any other 5xxINTERNAL

Every status the framework answers has its class, and each code is read off the standard that names that class. Where one status answers a class by its own name, the code is that name as its title spells it — 413 Content Too Large is CONTENT_TOO_LARGE. Where the reason phrases name no such class, the standard that does gives the code: gRPC’s canonical names for a class several statuses share or one whose phrase misnames it (INVALID_ARGUMENT for both 400 and 422, UNAUTHENTICATED for a 401 whose phrase says Unauthorized, UNAVAILABLE for 503, INTERNAL for any other 5xx), and RFC 6585’s rate limiting for 429’s RATE_LIMITED. A status the framework never writes, a 402 or a 451, carries no code. A client keys on the status, on that code, or on a type of your own set with .with_type(…).

Builders extend the body:

BuilderField
.with_detail("…")Free-form human-readable description
.with_instance("/posts/17")URI of the specific occurrence
.with_type("urn:problem:post-invalid")Override the type URI
.with_title("Post invalid")Override the title
ProblemDetails::from_error(status, title, &err)Build from an error: its sentence, a decode failure in it said without the value

The response carries Content-Type: application/problem+json automatically; an absent detail or instance is omitted from the body (per RFC 9457). Body shape, when all fields are set:

{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "post 9c3d… does not exist",
"instance": "/posts/9c3d…",
"code": "NOT_FOUND"
}