GraphQL alerting: HTTP status codes vs. response-body errors array for low-noise failure detection

Direct answer

Alert on the response body’s errors array, not the HTTP status code. GraphQL over HTTP conventionally returns 200 OK even when resolver exceptions, validation failures, or authorization denials occur, so status-code monitoring misses most application failures. To keep alerts low-noise, do not page on every errors entry. Partial-success responses can contain both data and errors, so route only systemic failures—such as repeated resolver exceptions or upstream outages—to alerts, and suppress or ticket expected field-level nullability errors.

Confirmed facts and uncertainty

Confirmed: the HTTP status line alone cannot detect most GraphQL application failures because the transport returns 200 OK while the JSON body carries errors. Confirmed: data and errors can appear in the same response.

Uncertain: exact extensions.code taxonomies. Apollo Router, GraphQL Yoga, Hasura, and custom gateways may emit different codes for resolver exceptions versus validation errors, and codes can change between versions. Treat codes such as INTERNAL_ERROR, UNAUTHENTICATED, BAD_USER_INPUT, or VALIDATION_FAILED as candidates to verify in your gateway, not as universal constants.

Recommended alert rule

1. Collect the full response body, not just the status code.
2. Parse errors and group by extensions.code when present.
3. Alert on codes that indicate systemic failure, such as repeated resolver exceptions or upstream timeouts.
4. Suppress expected partial-data errors by path depth or known field-level codes, or send them to a low-priority queue.
5. Use HTTP 5xx or connection failures as a separate infrastructure alert for transport or gateway unavailability.

Verification steps

curl -s -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ user(id: \"missing\") { name email } }"}' | jq '.errors[] | {message, path, extensions}'

Confirm that the HTTP status is 200 while errors is non-empty, then record the actual extensions.code values your gateway emits for resolver failures versus validation failures.

Missing diagnostic detail

Which gateway and version are you running? The filterable extensions fields and their stability depend on the implementation, so the recommendation changes if your gateway does not emit codes at all.