◆Error Codes Wiki

GraphQL Error Handling — Best Practices for API Error Responses

Warning5xx server error

Overview

Learn GraphQL error handling patterns including partial data responses, error extensions, and proper error classification for robust API development.

Key Details

  • GraphQL always returns HTTP 200 even when errors occur, making traditional status code monitoring insufficient
  • Errors are returned in a top-level 'errors' array alongside partial 'data' responses
  • Each error object contains message, locations, path, and optional extensions fields
  • Error extensions allow custom error codes and classification metadata
  • Partial data responses mean some fields resolve while others fail

Common Causes

  • Resolver throwing unhandled exceptions during field resolution
  • Validation errors in query syntax or variable types
  • Authorization failures on specific fields or types
  • Downstream service timeouts causing partial failures

Steps

  1. 1Implement a custom error formatter in your GraphQL server to standardize error responses
  2. 2Use error extensions to add machine-readable codes: { extensions: { code: 'UNAUTHENTICATED' } }
  3. 3Create custom error classes (AuthenticationError, ValidationError, NotFoundError) extending GraphQLError
  4. 4Set up error monitoring that inspects the errors array, not just HTTP status codes
  5. 5Use union types for expected errors: type Result = Success | NotFound | ValidationError

Tags

graphqlerror-handlingapipartial-dataextensions

More in 5xx Server Error

http-500-internal-server-errorHTTP 500 Internal Server Error — What It Means & How to Fix It
Critical
http-501-not-implementedHTTP 501 Not Implemented — What It Means & How to Fix It
Critical
http-502-bad-gatewayHTTP 502 Bad Gateway — What It Means & How to Fix It
Critical
http-503-service-unavailableHTTP 503 Service Unavailable — What It Means & How to Fix It
Critical
http-504-gateway-timeoutHTTP 504 Gateway Timeout — What It Means & How to Fix It
Critical
http-505-http-version-not-supportedHTTP 505 HTTP Version Not Supported — What It Means & How to Fix It
Critical

Frequently Asked Questions

GraphQL can return partial data with some fields succeeding and others failing. A 200 status indicates the request was processed, while the errors array details any field-level failures.