Error Handling in GraphQL Responses
What you'll learn: How GraphQL communicates errors while staying true to its single-endpoint architecture.
The Single-Endpoint Challenge
Unlike REST APIs that use HTTP status codes (404, 500, etc.) to signal different error types, GraphQL always returns a 200 OK status code at the HTTP level—even when something goes wrong. This is because GraphQL operates as a single endpoint and can return partial data: some fields might succeed while others fail in the same request.
The GraphQL Error Model
GraphQL responses have a two-part structure:
{
"data": {
"user": { "name": "Alice" },
"posts": null
},
"errors": [
{
"message": "Database connection failed",
"locations": [{ "line": 2, "column": 3 }],
"path": ["posts"]
}
]
}
The data field contains whatever could be successfully resolved (even if it's null). The errors array provides meaningful details about what went wrong, including:
- message: Human-readable error description
- path: Which field in the query failed
- locations: Where in the query the error occurred
Balancing Information with Structure
Think of GraphQL errors like a teacher grading an exam: they mark each question individually rather than failing the entire test. This allows clients to use the data that did succeed while handling specific failures gracefully.
You can extend errors with custom fields like error codes or types:
"errors": [{
"message": "Unauthorized",
"extensions": {
"code": "FORBIDDEN",
"userId": 123
}
}]
Key Takeaway: GraphQL separates transport-level success (HTTP 200) from application-level errors, using a structured errors array alongside partial data to provide detailed, field-specific error information without abandoning its single-endpoint model.