GraphQL error codes
The extensions a client branches on — extensions.code, a problem's type and title, and the field map keyed by the schema's own names.
A GraphQL error carries its sentence on message and what a client branches on
under extensions: a stable code, a problem type when the error has one, and a
map of the input fields that failed. GraphQL errors is which
error answers what; this page is the vocabulary those answers share.
Extensions and codes
Section titled “Extensions and codes”extensions.code is the stable class a client branches on without parsing the
message. The framework’s codes are constants in nest_rs::core::code
— UNAUTHENTICATED, FORBIDDEN, INSUFFICIENT_SCOPE, RATE_LIMITED,
UNAVAILABLE, INVALID_ARGUMENT, NOT_FOUND, CONFLICT, INTERNAL, and one
per other status the framework answers, from METHOD_NOT_ALLOWED to
UPGRADE_REQUIRED. Each is read off the standard that names its class: the
HTTP status’s reason phrase in upper snake case for a class one status answers
by that name, gRPC’s canonical name for a class several statuses share or
whose phrase misnames it (INVALID_ARGUMENT, UNAUTHENTICATED,
UNAVAILABLE, INTERNAL), RFC 6750’s error code for INSUFFICIENT_SCOPE,
and RFC 6585’s rate limiting for RATE_LIMITED. Every refusal
the framework writes reads them: a guard’s denial, the by-id binding (a bind
argument that is not a UUID v7 answers "id must be a UUID v7" under
INVALID_ARGUMENT, the twin of the HTTP path’s 400), an opaque failure.
A feature’s own error says its class through ToProblem, once for every
edge — GraphQL, HTTP (HTTP errors), WebSockets and MCP:
use nest_rs::core::{Code, Problem, ToProblem, code};
pub const SLUG_TAKEN: Code = Code::new("SLUG_TAKEN");
#[derive(Debug, thiserror::Error)]pub enum PublishError { #[error("the slug is taken")] SlugTaken, #[error("the post is not a draft")] NotADraft, #[error("the search index refused the post")] Index(#[source] std::io::Error),}
impl ToProblem for PublishError { fn to_problem(&self) -> Option<Problem> { match self { Self::SlugTaken => Some(Problem::new(409, SLUG_TAKEN).with_detail("the slug is taken")), Self::NotADraft => Some(Problem::new(409, code::CONFLICT)), Self::Index(_) => None, } }}#[mutation]#[authorize(Update, posts::Entity)]async fn publish(&self, id: String) -> Result<Post, PublishError> { self.svc.publish(&id).await}{ "errors": [ { "message": "the slug is taken", "extensions": { "code": "SLUG_TAKEN" }, "path": ["publish"] } ]}A problem with a type of its own, Problem::with_type(uri, title), adds
"type" and "title" to the extensions, the URI a client keys on, and a field
map, with_errors, "errors". A problem without a detail says its code in
words (NOT_A_DRAFT would read not a draft); a 5xx never carries one — a 503 answers
"service unavailable", the chain behind it filed at warn on nest_rs::graphql, any
other "internal error", its chain at error. None is the opaque answer:
Index’s chain is filed at error, the client reads the constant. A
Code declared in a const is checked when it compiles: Code::new("conflict")
is refused, and so is a Problem whose status is not a 4xx or a 5xx.
Field errors use the schema’s names
Section titled “Field errors use the schema’s names”extensions.errors names a field as the schema spells it, so a client matches
a key to the field it sent. A Rust field display_name answers displayName, at
every depth, a validation failure and a #[crud] conflict
alike, while an input declaring rename_fields = "snake_case" keeps display_name:
{ "message": "validation failed", "extensions": { "code": "INVALID_ARGUMENT", "errors": { "displayName": [{ "code": "length" }] } }}A key is matched against the names the schema’s inputs and arguments serve, by
what is left once case and underscores are set aside. So a key no input serves
stays as it was said, and so does __all__, validator’s key for a rule over a
whole struct, and one whose field #[graphql(name = "…")] renamed to another
word, which the schema’s names cannot tell. Where two inputs of one schema spell
one word differently, a key that is one of those spellings stays, and any other
takes the first by input name. A
variable pipe runs before the schema does and
answers the map it wrote.
Going further
Section titled “Going further”- GraphQL errors — which error answers which envelope, and what the client is never owed.
- HTTP errors — the same
ToProblem, answered as a problem document. - Global pipes — the variable pipe whose map a field error keeps.