HTTP errors
Map handler errors to HTTP responses — ToProblem on a feature error enum, ProblemDetails for one-off RFC 9457 bodies.
A handler returning Err(MyError) should produce a typed JSON body and
the right status — never a stack trace, never a generic 500. The HTTP
surface gives two paths to get there. A feature with its own error enum
implements nest_rs::core::ToProblem once — the one mapping GraphQL,
WebSockets and MCP answer it by too — and a route returning it answers the
problem it says. A glue route without an enum picks up ProblemDetails
— a small builder that emits an RFC 9457 application/problem+json
body.
For a wider tour of the error-handling seams (typed catches, unconditional
mapping, the ToProblem default), see
Error handling.
Map a feature error with ToProblem
Section titled “Map a feature error with ToProblem”The pattern is thiserror::Error for the error type, ToProblem for what
the client reads of each variant: a Problem, its status and the code a
client branches on, and when you have one, a problem type of your own:
use nest_rs::core::{Problem, ToProblem, code};use thiserror::Error;use nest_rs::http::Json;
const NAME_RESERVED: Problem = Problem::new(409, code::CONFLICT).with_type( "https://example.com/problems/name-reserved", "Name reserved",);
#[derive(Debug, Error)]pub enum GreetError { #[error("name must not be empty")] EmptyName, #[error("name reserved")] Reserved,}
impl ToProblem for GreetError { fn to_problem(&self) -> Option<Problem> { match self { GreetError::EmptyName => { Some(Problem::new(400, code::INVALID_ARGUMENT).with_detail(self.to_string())) } GreetError::Reserved => Some(NAME_RESERVED.with_detail(self.to_string())), } }}
#[post("/")]async fn shout(&self, Json(input): Json<GreetInput>) -> Result<Json<GreetReply>, GreetError> { if input.name.trim().is_empty() { return Err(GreetError::EmptyName); } Ok(Json(GreetReply { greeting: format!("HELLO, {}", input.name.to_uppercase()) }))}The route reads its error by its type, as every edge does, and answers the problem document:
{ "type": "https://example.com/problems/name-reserved", "title": "Name reserved", "status": 409, "detail": "name reserved", "code": "CONFLICT"}with_type(uri, title) names a problem type of your own (RFC 9457 §3.1): a
URI a client keys on and dereferences for its documentation, and its title,
the same for every occurrence. Declared in a const, the URI is checked when
it compiles. Without it the document is about:blank, its title the status’s
reason phrase. GraphQL answers the same problem with extensions.type and
extensions.title, WebSockets and MCP with data.type and data.title. A
detail and a field map (with_errors) go out on a 4xx only; returning
None answers the opaque 500.
A body that answers the edge’s own error — mixing yours with ProblemDetails
or a bare status — converts it with ?: self.svc.publish(id).await? answers
the problem it says, since every ToProblem error is a
nest_rs::http::ResponseError. An answer that is no problem document at all,
another protocol’s body or an envelope of your own, implements
ResponseError instead: its status(), and as_response() for the body. One
error is mapped one way: a ResponseError written for a type that implements
ToProblem does not compile.
Either rendering keeps a 5xx’s cause for the operator, and neither logs it
itself. The edge files the error’s whole chain once the answer is final,
on nest_rs::http: at error, at warn behind a 503, naming the route as the
http.request line does, by verb and path. It goes by the
status the client was finally sent, so an exception
filter that answers the failure with a
4xx files nothing. A 4xx your error answers is the client’s own, and
files nothing either.
A feature owns one error type — usually the one it already returns from
its service. The framework’s plumbing errors carry their own HTTP mapping:
nest_rs::seaorm::ServiceError implements ToProblem and converts into
HttpError through it, and the OAuth nest_rs::oauth::server::TokenError and
nest_rs::authn::AuthError, which answer another protocol’s body or a
challenge, ship ResponseError impls, so service-layer ? works without a
feature-level conversion — see
the table below.
Structured bodies with ProblemDetails
Section titled “Structured bodies with ProblemDetails”A glue route that doesn’t own a feature error enum still answers an RFC 9457
problem document: ProblemDetails::not_found().with_detail(…) built inline,
? returning it. Problem details lists its
constructors, the code each status carries and its builders.
When to pick which
Section titled “When to pick which”| Situation | Use |
|---|---|
| The error is a variant of a feature’s own enum, used by ≥ 2 routes | ToProblem on the enum |
| A one-off route raises a problem the enum doesn’t model (e.g. a glue route checking a precondition) | ProblemDetails inline |
The service returns a framework error (ServiceError, TokenError, AuthError, …) | Nothing — the framework’s own mapping already renders it |
| The body shape must match an external spec (CloudEvents, your own envelope) | ResponseError on an error of its own, its as_response writing the body |
A feature’s own error type is the canonical home. ProblemDetails is
the right tool for the leftovers — never the goal.
An error the client is not owed
Section titled “An error the client is not owed”Everything above decides how an error is shaped. Opaque decides whether
the client sees it at all.
ServiceError is wire-safe by construction — its Internal variant, and a Db
one but for a statement Postgres cancelled at its bound (the
table below), answer a 500 whose code is INTERNAL, with no
detail, and display no cause, even wrapped in an error of yours; its log
line says the database’s failure by its SQLSTATE, never by the server’s
message, which quotes the input it refused. A failure of your own that is no
database error keeps its cause the same way:
ServiceError::internal_because("could not sign the export", err) answers
that 500 whatever err holds, and the operator’s line reads the detail,
then err’s chain. A feature’s own error
type has no such discipline imposed on it, and a Display that wraps a
driver error carries SQL, column names and sometimes row values into the
response body.
use nest_rs::http::Opaque;use nest_rs::http::Json;use nest_rs::http::Path;use uuid::Uuid;
#[get("/reports/{id}")]#[authorize(Read, reports::Entity)]async fn report(&self, Path(id): Path<Uuid>) -> Result<Json<Report>> { Ok(Json(self.svc.render(id).await.opaque()?))}.opaque()? answers the opaque 500 and keeps the real error for the operator:
the edge files it at error on nest_rs::http once that answer goes out, naming
the route, and an exception filter answering the failure with a 4xx leaves no
line. The 500 is the one document every server failure the framework does not
describe is on HTTP — a ServiceError’s, a #[crud] operation’s, a panic’s,
an unknown error’s alike:
{ "type": "about:blank", "title": "Internal Server Error", "status": 500, "code": "INTERNAL"}A client reads the code and nothing else, whichever part answered, so an
opaque failure is not identifiable by its shape.
Reach for it on a failure that is none of the caller’s business. A validation rejection or an authorization denial is the opposite case: those exist to be read, and travel as themselves. The same seam reads identically on GraphQL, WebSockets and MCP.
Framework errors carry their own mapping
Section titled “Framework errors carry their own mapping”The framework’s error types carry their own HTTP mapping, so they surface on a handler that calls a service without a single line of conversion code:
| Error | Source | Renders as |
|---|---|---|
nest_rs::seaorm::ServiceError | Repo, CrudService, dataloader | ToProblem — problem+json with its code, 400 validation, as the edge’s own check answers, 422 invalid, 409 conflict (a unique violation among them), 403 forbidden, 404 not found, 503 a statement Postgres cancelled at its bound (with the bound as its Retry-After), 500 else (validation field errors ride as errors) |
nest_rs::oauth::server::TokenError | OAuth token endpoint: the handler, ClientAuthenticationGuard, AccessTokenRequest | ResponseError — application/json per RFC 6749 §5.2, never a problem document — 400 bad grant/scope, a request that does not parse (invalid_request, its error_description saying where) or a client refused without HTTP authentication, 401 invalid_client with a Basic challenge for a client refused over the Authorization header, 500 signing, 503 a dependency that did not answer |
nest_rs::authn::AuthError | Strategy authentication | ResponseError — 401 challenge (503, with a Retry-After when known, when the identity store or provider is unavailable) |
nest_rs::authn::SignError | JwtService::sign, OAuthClient::authorize | ToProblem saying none — the opaque 500 |
Every error the HTTP transport renders — a handler’s ServiceError, an
inline ProblemDetails, a validation rejection, and even a raw router
error (an unmounted-route 404, a 413 over the body cap) — comes back
as one application/problem+json body. The transport lifts any leftover
plain-text error onto the RFC 9457 envelope at its edge, under its status’s
code from the table above — an unmounted route’s 404 reads NOT_FOUND,
as a #[crud] row nobody can see does; a 5xx answers its class’s document
with no detail, so a driver or panic message never reaches the wire.
An error nobody meant for the client — an anyhow chain a route returns
(anyhow::Result<T>), one a body says .opaque()? of, an
HttpError::new(e, StatusCode::INTERNAL_SERVER_ERROR) — is never lost on the way: it answers the
opaque 500, and its whole chain is filed once at error on
nest_rs::http. So is the chain behind a framework error’s 5xx, the one
line its failure gets: a ServiceError’s database error, a SignError or a
TokenError’s signing failure, and at warn an AuthError’s or a TokenError’s 503. A
nest_rs::core::Problem the chain carries answers itself
instead — its status, its type and title, its detail and field map on a
4xx, its code as an extension member and its Retry-After — the same
contract GraphQL, WebSockets and MCP answer it by
(ProblemDetails::from_problem builds the document).
A handler that panics answers that same opaque 500, with nothing of the panic
in it, and its connection serves the next request. The panic is filed once at
error on nest_rs::http with where it happened, and the request’s line says
outcome="panic" (see The operation log).
A streaming body that panics mid-flow cannot be finished, so it ends there.
Each of them converts into HttpError, so ? propagates it through a
nest_rs::http::Result handler, and a handler may also return it as its own
error type (Result<T, AuthError>).
There is no AbilityError — an ability denial is not a handler’s error. It
is a Denial, the type a guard refuses with: the class gate that
#[authorize(Action, Entity)] declares checks the ability your AuthzGuard
attached and answers its Denial before the handler runs: Denial::forbidden when no
grant covers the action, Denial::insufficient_scope for a token too narrow,
Denial::unauthorized for an anonymous caller off a #[public] route. It never
travels the ? path at all (see
Guards). Its document’s code is the one the
denial’s class carries on every edge: UNAUTHENTICATED for a missing or
rejected credential, FORBIDDEN, INSUFFICIENT_SCOPE for a token too
narrow, RATE_LIMITED, UNAVAILABLE, INTERNAL — so a client branches on
one code whether the refusal reached it over HTTP, GraphQL, WebSockets or MCP.
A feature only writes its own error enum for genuinely domain-specific wire contracts (a custom error code clients key on) or for security-opaque variants — anything the framework already speaks should keep using the framework’s mapping.
Going further
Section titled “Going further”- Error handling — the wider story:
an exception filter for a typed catch or one envelope for every error,
ToProblemas the default. - Responses — the success side, and how
#[http_code]leaves a handler’sErrstatus untouched. - Controllers & routes — the route table.