GraphQL Error Handling — Best Practices for API Error Responses
About GraphQL Error Handling
Learn GraphQL error handling patterns including partial data responses, error extensions, and proper error classification for robust API development. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.
Here are the key things to understand: 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. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.
The most common reasons this occurs include: 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. Identifying the root cause is the first step toward finding the right solution.
To resolve this, follow these recommended steps: Implement a custom error formatter in your GraphQL server to standardize error responses. Use error extensions to add machine-readable codes: { extensions: { code: 'UNAUTHENTICATED' } }. Create custom error classes (AuthenticationError, ValidationError, NotFoundError) extending GraphQLError. Set up error monitoring that inspects the errors array, not just HTTP status codes. Use union types for expected errors: type Result = Success | NotFound | ValidationError. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.
This article is part of our HTTP Status Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.
Quick Answer
Why does GraphQL return 200 for errors?
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.
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
- 1Implement a custom error formatter in your GraphQL server to standardize error responses
- 2Use error extensions to add machine-readable codes: { extensions: { code: 'UNAUTHENTICATED' } }
- 3Create custom error classes (AuthenticationError, ValidationError, NotFoundError) extending GraphQLError
- 4Set up error monitoring that inspects the errors array, not just HTTP status codes
- 5Use union types for expected errors: type Result = Success | NotFound | ValidationError