GraphQL error handling differs from typical REST patterns because errors are returned in a structured errors array and may coexist with partial data. Testers need to verify not only that errors occur when they should, but also that they are reported clearly and safely without leaking internal details.
GraphQL Errors, Extensions, and Partial Data
When something goes wrong, GraphQL servers populate the errors array with objects that include messages, locations, and sometimes extensions with additional metadata. In many cases, data may still contain successfully resolved fields alongside errors. Tests should assert on the presence, shape, and content of these error objects.
{
"data": {
"customer": null
},
"errors": [
{
"message": "Customer not found",
"path": ["customer"],
"extensions": { "code": "NOT_FOUND" }
}
]
}Validation errors often occur when required arguments are missing, types are wrong, or values violate business rules. GraphQL tooling can catch some of these at parse time, but applications also enforce domain-specific constraints that tests must cover.
Designing Error and Validation Tests
Create tests for invalid input types, missing required variables, constraint violations (such as invalid email formats), and permission errors. Verify both that the correct error codes are returned and that data is either omitted or present only where appropriate in partial responses.
Common Mistakes
Mistake 1 — Ignoring partial success scenarios
Assuming all-or-nothing behaviour is incorrect in many GraphQL APIs.
❌ Wrong: Only testing cases where everything succeeds or fails entirely.
✅ Correct: Include tests where some fields resolve while others produce errors.
Mistake 2 — Asserting only on HTTP status codes
This misses GraphQL-specific error information.
❌ Wrong: Treating HTTP 200 as success without inspecting the errors array.
✅ Correct: Assert on both data and errors, including error shapes and codes.