Error Handling in Queries and Mutations
You'll learn: How to properly handle different types of errors that occur when executing GraphQL queries and mutations.
Why GraphQL Errors Are Different
Unlike REST APIs that signal errors primarily through HTTP status codes, GraphQL almost always returns a 200 OK status—even when something goes wrong. Instead, GraphQL wraps errors in a structured errors array alongside your data, allowing for partial success scenarios where some fields succeed while others fail.
Three Types of GraphQL Errors
1. Field-Level Errors
When a specific field in your query can't be resolved, GraphQL returns null for that field and includes an error in the errors array. The path property tells you exactly which field failed.
// Response with field-level error
{
"data": {
"user": {
"name": "Alice",
"email": null // This field failed
}
},
"errors": [
{
"message": "Email service unavailable",
"path": ["user", "email"]
}
]
}
2. Network Errors
These occur before the request reaches the GraphQL server—connection failures, timeouts, or DNS issues. Handle these separately from GraphQL errors since they won't have the standard GraphQL response structure.
3. Partial Success
GraphQL's superpower: you might get some valid data even when errors occur. Always check both data and errors in your response handler.
const response = await fetch('/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query })
});
const result = await response.json();
if (result.errors) {
// Handle GraphQL errors
console.error('GraphQL errors:', result.errors);
}
if (result.data) {
// Use partial or complete data
console.log('Data received:', result.data);
}
Key Takeaway: In GraphQL, always check both the errors and data fields in responses—errors don't prevent partial data from being returned, and a 200 status doesn't guarantee success.