@@ -16,7 +16,7 @@ than a definitive reference.
1616### What it means
1717
1818The server couldn't parse your request. Either the GraphQL query string is malformed,
19- or the JSON body isn't valid.
19+ or the JSON body isn't valid. This is the primary error status recommended by the GraphQL over HTTP specification.
2020
2121### Common causes
2222
@@ -49,44 +49,6 @@ and may allow `GET` for queries.
4949- Refer to the [ GraphQL over HTTP spec] ( https://graphql.github.io/graphql-over-http/draft/ ) to
5050confirm method support.
5151
52- ## ` 415 Unsupported Media Type `
53-
54- ### What it means
55-
56- The server doesn't understand the request's ` Content-Type ` .
57-
58- ### Common causes
59-
60- - Sending a GraphQL query with ` Content-Type: text/plain ` or another unsupported type
61- - Omitting the ` Content-Type ` header in a ` POST ` request
62-
63- ### How to debug
64-
65- - Set the header explicitly: ` Content-Type: application/json ` .
66- - If you're using ` application/graphql ` , verify your server supports it. This content type
67- is optional.
68-
69- ## ` 422 Unprocessable Entity ` : Missing or invalid ` query `
70-
71- ### What it means
72-
73- The server received the request, but the ` query ` field was missing or invalid.
74-
75- ### Common causes
76-
77- - Sending ` {} ` with no ` query ` key
78- - Sending variables or an operation name without a query
79-
80- ### How to debug
81-
82- Always include a ` query ` field in your request body. For example:
83-
84- ``` json
85- {
86- "query" : " { user(id: 1) { name } }"
87- }
88- ```
89-
9052## ` 500 Internal Server Error ` : Unexpected server failures
9153
9254### What it means
@@ -138,6 +100,18 @@ If there's no `data` field, the request likely failed during validation. For exa
138100
139101Use introspection or an IDE to verify your query matches the schema.
140102
103+ ## Implementation-specific status codes
104+
105+ Some GraphQL server implementations may use additional HTTP status codes that are not explicitly recommended
106+ by the specification. These vary by implementation.
107+
108+ - ` 415 Unsupported Media Type ` : The server doesn't understand the request's ` Content-Type ` . This can occur
109+ when a GraphQL query is sent with ` Content-Type: text/plain ` or another unsupported type.
110+ - ` 422 Unprocessable Entity ` : Some implementations use this for GraphQL validation errors instead of ` 200 ` + errors array.
111+
112+ These error codes are not recommended by the specification for most cases. Different GraphQL servers handle
113+ validation errors differently. When in doubt, use error codes supported by the specification.
114+
141115## Understanding GraphQL response formats
142116
143117Most GraphQL servers return responses using the ` application/json ` media type. However,
0 commit comments