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:
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 and codes
Section titled “Constructors and codes”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:
| Status | code |
|---|---|
400, 422 | INVALID_ARGUMENT |
401 | UNAUTHENTICATED |
403 | FORBIDDEN |
404 | NOT_FOUND |
405 | METHOD_NOT_ALLOWED |
406 | NOT_ACCEPTABLE |
408 | REQUEST_TIMEOUT |
409 | CONFLICT |
410 | GONE |
412 | PRECONDITION_FAILED |
413 | CONTENT_TOO_LARGE |
415 | UNSUPPORTED_MEDIA_TYPE |
416 | RANGE_NOT_SATISFIABLE |
426 | UPGRADE_REQUIRED |
429 | RATE_LIMITED |
503 | UNAVAILABLE |
any other 5xx | INTERNAL |
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
Section titled “Builders”Builders extend the body:
| Builder | Field |
|---|---|
.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"}Going further
Section titled “Going further”- HTTP errors —
ToProblemon a feature’s own error, and when to pick which. - GraphQL error codes — the same codes, read under
extensions.code.