Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitfb6c6ea

Browse files
docs: add guide on graphql-http errors (#2006)
Co-authored-by: Benjie <benjie@jemjie.com>
1 parent70812d4 commitfb6c6ea

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)
[8]ページ先頭
©2009-2025 Movatter.jp