GraphQL Error Handling

Classes: 12 | Total time: ~4 hours | Difficulty: Intermediate

---

Why this course exists

Error handling is the least standardized part of GraphQL in practice. The specification defines the shape of the errors list in a response, but it deliberately leaves the rest undefined: no error vocabulary, no status-code rules, no guidance on where business errors belong. Every team fills that gap on its own, so the same failure looks different from one API to the next:

• One API returns null with a cryptic top-level error.
• Another returns a userErrors list inside the mutation payload.
• A third wraps every result in a union type.

The community has spent a decade converging on answers, and the specifications have been catching up:

• The GraphQL specification. The September 2025 edition, the first since October 2021, tightened the response and error wording this course quotes. Its changelog includes PR #1152, which renamed "field error" to "execution error".
• GraphQL over HTTP. The GraphQL-over-HTTP draft now says which HTTP status codes a server should send.
• Nullability. The work now continues in the main GraphQL working group, where the error behaviors proposal changes how errors and null interact during execution. The dedicated nullability working group was archived in February 2026.

This course collects all of it in one place. The material that exists elsewhere on this site stays where it is: the introduction's errors chapter and the Spring GraphQL tutorial's error handling class each serve their own course's narrative. Our frontend tutorial, coming soon, has an error handling class of its own. This course covers the topic in depth, and you can follow it without reading those chapters first.

The four parts

Foundations (Classes 1 to 3)

• Class 1 dissects the error model the specification defines: request errors, execution errors and the anatomy of an error. It also covers the execution rules that turn a failing field into null plus an error in the errors list, while the rest of the response still arrives.
• Class 2 follows one error as it propagates through non-null positions, and shows precisely why today's null is ambiguous.
• Class 3 moves to the transport: the GraphQL-over-HTTP specification's media types and status-code rules. It covers the draft's new 294 status for partial success, the exact conditions for 4xx and 5xx replies, and how errors travel when the proposed @defer and @stream directives split a response into several parts.

Designing for errors (Classes 4 to 6)

• Class 4 builds an error taxonomy and a stable extensions.code vocabulary, surveying the conventions Apollo Server and Netflix DGS ship.
• Class 5 covers errors as data: union result types, interface-based error types, and the line between expected business outcomes (which belong in the schema) and failures (which belong in the errors list).
• Class 6 implements all of it in Spring GraphQL on the Movie Database, with side notes where Netflix DGS, Apollo Server, and Hot Chocolate differ. It ends with tests that check which errors the server returns for each kind of request, and describes what changes when a federated router stands between your subgraph and the client.

Client and future (Classes 7 and 8)

• Class 7 covers the client half: Apollo Client's error policies, urql, Relay's explicit error model, and the JVM pair of Spring's GraphQlClient and Apollo Kotlin. It also covers rendering partial data and what nulls caused by errors do to normalized caches.
• Class 8 is the forward-looking chapter: semantic nullability, the @semanticNonNull directive, and the proposed onError request property that lets a client choose between error propagation, halting, and treating every response position as an error boundary.

Case studies and synthesis (Classes 9 to 12)

Three chapters examine how real organizations handle errors, using only public primary sources, and a final chapter brings the course together:

• Class 9 takes Shopify's userErrors pattern.
• Class 10 takes GitHub and GitLab, two public APIs that chose opposite designs.
• Class 11 takes Meta and Relay as the origin of semantic nullability, with a shorter look at Netflix DGS.
• Class 12 distills the whole course into a decision framework and a consolidated set of guidelines.

Who this course is for

The course is for engineers who have built or operated a GraphQL API or a GraphQL client and now need to get error handling right, either in a schema they own or in guidance they give to other teams. The server chapters (Class 6 in particular) assume the Spring GraphQL tutorial or equivalent experience, and reuse its Movie Database domain. The rest of the course is framework-neutral: it teaches from the specifications and from documented public implementations, and the concepts transfer to any server or client stack.

A note on moving targets

Two of the primary sources this course leans on are drafts: the GraphQL-over-HTTP specification and the nullability proposals open against the GraphQL specification (PR #1163, PR #1208 and PR #1236); the nullability working group archive preserves the history behind them. Wherever a chapter depends on them, it says so and dates the claim (the course was last checked against the drafts on 22 September 2026). Chapters quote each draft's own maturity label, and the Further Reading sections link the living documents so you can check what has changed since.