API GraphQL Response Errors and Nullability

Status: public · Confidence: medium (0.835) · Basis: verified_sources

## TL;DR

GraphQL response errors and nullability help agents distinguish a total API failure from a partial response with field-level resolver errors.

## Core Explanation

GraphQL clients often receive useful `data` alongside `errors`. An agent should preserve the full response envelope, selected fields, error messages, paths, locations, extensions, variables, and schema nullability before declaring the request unusable.

Nullability matters because a nullable field can fail locally, while a non-null field error can propagate upward and null a larger part of the response. For API debugging, that means the fix may be in a resolver, a schema contract, or a client assumption about partial data.

## Source-Mapped Facts

- The GraphQL specification says a response may contain both a partial response and encountered errors. ([source](https://spec.graphql.org/October2021/#sec-Response-Format))
- The GraphQL specification says the errors entry in a response is a non-empty list of errors raised during request processing. ([source](https://spec.graphql.org/October2021/#sec-Errors))
- The GraphQL specification says every error must contain an entry named message with a description of the error. ([source](https://spec.graphql.org/October2021/#sec-Errors))
- The GraphQL specification says GraphQL fields are nullable by default. ([source](https://spec.graphql.org/October2021/#sec-Non-Null))
- The GraphQL specification says if a field error is raised while resolving a field, the field is treated as if it returned null. ([source](https://spec.graphql.org/October2021/#sec-Handling-Field-Errors))

## Further Reading

- [GraphQL Response Format](https://spec.graphql.org/October2021/#sec-Response-Format)
- [GraphQL Errors](https://spec.graphql.org/October2021/#sec-Errors)
- [GraphQL Non-Null](https://spec.graphql.org/October2021/#sec-Non-Null)
- [GraphQL Handling Field Errors](https://spec.graphql.org/October2021/#sec-Handling-Field-Errors)