Skip to content

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.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:

crates/features/src/posts/error.rs
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,
}
}
}
crates/features/src/posts/graphql/resolver.rs
#[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.

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.

  • 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.