Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 7bde26c

Browse files
authoredJun 19, 2025··
Apply suggestions from code review
1 parent 176d140 commit 7bde26c

File tree

1 file changed

+20
-10
lines changed

1 file changed

+20
-10
lines changed
 

‎src/pages/learn/debug-errors.mdx

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -74,10 +74,17 @@ The HTTP layer succeeded, but the GraphQL operation produced errors.
7474

7575
### Common causes
7676

77+
- Runtime errors during execution
78+
- Violating schema constraints (e.g. returning the wrong data type, or `null` in a non-nullable position)
79+
80+
Older servers and clients (those not using
81+
`Content-Type: application/graphql-response+json`) may also use 200 OK in the case of
82+
complete request failure (no `data`). Common causes include:
83+
7784
- Querying a field that doesn't exist
7885
- Passing incorrect arguments to a field
79-
- Violating schema constraints, such as non-nullability
80-
- Runtime errors during execution
86+
- Omitting a selection set on a non-leaf field
87+
- Failure to specify the `operationName` when multiple operations exist in the request
8188

8289
### How to debug
8390

@@ -114,18 +121,21 @@ validation errors differently. When in doubt, use error codes supported by the s
114121

115122
## Understanding GraphQL response formats
116123

117-
Most GraphQL servers return responses using the `application/json` media type. However,
118-
the [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/draft/) recommends
119-
using a more specific type: `application/graphql-response+json`.
124+
Traditionally, GraphQL servers have returned responses using the `application/json` media type.
125+
However, the [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/draft/) recommends
126+
that clients request (and servers respond with) a more specific type: `application/graphql-response+json`.
120127

121-
This media type identifies the payload as a GraphQL response and helps clients
122-
distinguish it from other types of JSON.
128+
This newer media type identifies the payload as a GraphQL response and helps clients
129+
distinguish it from other types of JSON, making the response safe to process even if
130+
it uses a non-2xx status code. A trusted proxy, gateway, or other intermediary
131+
might describe an error using JSON, but would never do so using `application/graphql-response+json`
132+
unless it was a valid GraphQL response.
123133

124134
### What to know
125135

126-
- Servers may respond with `application/graphql-response+json` instead of
136+
- Servers may respond with `application/graphql-response+json` or
127137
`application/json`.
128-
- Clients can request this media type using the `Accept` header: `Accept: application/graphql-response+json`
129-
- This content type is optional, but support for it is growing.
138+
- Clients can request this media type using the `Accept` header: `Accept: application/graphql-response+json, application/json;q=0.9` (prefer the new media type over the old one, but accept both)
139+
- This content type is recommended, and support for it is growing.
130140
- If your client uses content negotiation, ensure your server can response with the appropriate
131141
type or fallback to `application/json`.

0 commit comments

Comments
 (0)
Please sign in to comment.