Skip to content

Commit fb6c6ea

Browse files
sarahxsandersbenjie
sarahxsanders
and
benjie
authored
docs: add guide on graphql-http errors (#2006)
Co-authored-by: Benjie <benjie@jemjie.com>
1 parent 70812d4 commit fb6c6ea

File tree

3 files changed

+151
-0
lines changed

3 files changed

+151
-0
lines changed

‎src/pages/learn/_meta.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,9 @@ export default {
2727
performance: "",
2828
security: "",
2929
federation: "",
30+
"-- 3": {
31+
type: "separator",
32+
title: "GraphQL over HTTP",
33+
},
34+
"debug-errors": "Common GraphQL over HTTP Errors",
3035
}

‎src/pages/learn/best-practices.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,5 +53,10 @@ The articles in this section should not be taken as gospel, and in some cases ma
5353
link: "/learn/security/",
5454
description: "Protect GraphQL APIs from malicious operations",
5555
},
56+
{
57+
title: "Common Errors",
58+
link: "/learn/debug-errors/",
59+
description: "Learn about common `graphql-http` errors and how to debug them.",
60+
}
5661
]}
5762
/>

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

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Common HTTP Errors and How to Debug Them
2+
3+
When building or consuming a GraphQL API over HTTP, it's common to run into
4+
errors, especially during development. Understanding how to recognize and resolve these issues
5+
can save you time and frustration.
6+
7+
This guide outlines common HTTP and GraphQL errors, what they mean, and how to debug them
8+
effectively. It follows the recommendations of the
9+
[GraphQL over HTTP spec (draft)](https://graphql.github.io/graphql-over-http/draft/),
10+
which standardizes how GraphQL works over HTTP, including request formats, status codes,
11+
and media types. Keep in mind that implementations may vary, so treat this as a general guide rather
12+
than a definitive reference.
13+
14+
## `400 Bad Request`: Syntax or parse errors
15+
16+
### What it means
17+
18+
The server couldn't parse your request. Either the GraphQL query string is malformed,
19+
or the JSON body isn't valid. This is the primary error status recommended by the GraphQL over HTTP specification.
20+
21+
### Common causes
22+
23+
- JSON syntax errors
24+
- Sending a plain string without wrapping it in `{ "query": "..." }`
25+
- Using `Content-Type: application/graphql` without supporting it
26+
27+
### How to debug
28+
29+
- Validate your JSON body using a linter or formatter.
30+
- Make sure you're sending a `POST` request with a `Content-Type: application/json` header.
31+
- Check your GraphQL query for syntax errors. Use an IDE or linter to verify it.
32+
33+
## `405 Method Not Allowed`: Wrong HTTP Method
34+
35+
### What it means
36+
37+
You're using an unsupported HTTP method. Most GraphQL servers require `POST` for mutations
38+
and may allow `GET` for queries.
39+
40+
### Common causes
41+
42+
- Sending a `PUT` or `DELETE` request instead of `POST` or `GET`
43+
- Sending a `GET` request for a mutation, or to a server that only supports `POST` requests
44+
45+
### How to debug
46+
47+
- Check your HTTP method. Mutations must use `POST`.
48+
- Make sure your server supports `GET` for queries.
49+
- Refer to the [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/draft/) to
50+
confirm method support.
51+
52+
## `500 Internal Server Error`: Unexpected server failures
53+
54+
### What it means
55+
56+
Something went wrong on the server.
57+
58+
### Common causes
59+
60+
- An unhandled exception in a resolver
61+
- Schema validation issues during server startup
62+
- Missing or misconfigured middleware
63+
64+
### How to debug
65+
66+
- Check server logs or stack traces.
67+
- Add error handling to resolvers.
68+
69+
## GraphQL errors with `200 OK`
70+
71+
### What it means
72+
73+
The HTTP layer succeeded, but the GraphQL operation produced errors.
74+
75+
### Common causes
76+
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+
84+
- Querying a field that doesn't exist
85+
- Passing incorrect arguments to a field
86+
- Omitting a selection set on a non-leaf field
87+
- Failure to specify the `operationName` when multiple operations exist in the request
88+
89+
### How to debug
90+
91+
Check the `errors` array in the response body. If the response includes a `data` property, then
92+
your query document is likely valid and you most likely hit a runtime exception - perhaps due to
93+
invalid input, access denial, or a bug in server logic.
94+
95+
If there's no `data` field, the request likely failed during validation. For example:
96+
97+
```json
98+
{
99+
"errors": [
100+
{
101+
"message": "Cannot query field \"foo\" on type \"Query\".",
102+
"locations": [{ "line": 1, "column": 3 }]
103+
}
104+
]
105+
}
106+
```
107+
108+
Use introspection or an IDE to verify your query matches the schema.
109+
110+
## Implementation-specific status codes
111+
112+
Some GraphQL server implementations may use additional HTTP status codes that are not explicitly recommended
113+
by the specification. These vary by implementation.
114+
115+
- `415 Unsupported Media Type`: The server doesn't understand the request's `Content-Type`. This can occur
116+
when a GraphQL query is sent with `Content-Type: text/plain` or another unsupported type.
117+
- `422 Unprocessable Entity`: Some implementations use this for GraphQL validation errors instead of `200` + errors array.
118+
119+
These error codes are not recommended by the specification for most cases. Different GraphQL servers handle
120+
validation errors differently. When in doubt, use error codes supported by the specification.
121+
122+
## Understanding GraphQL response formats
123+
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`.
127+
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.
133+
134+
### What to know
135+
136+
- Servers may respond with `application/graphql-response+json` or
137+
`application/json`.
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.
140+
- If your client uses content negotiation, ensure your server can response with the appropriate
141+
type or fallback to `application/json`.

0 commit comments

Comments
 (0)