diff --git a/src/pages/learn/_meta.ts b/src/pages/learn/_meta.ts index ded3ef9830..f5c7a1887b 100644 --- a/src/pages/learn/_meta.ts +++ b/src/pages/learn/_meta.ts @@ -27,4 +27,9 @@ export default { performance: "", security: "", federation: "", + "-- 3": { + type: "separator", + title: "GraphQL over HTTP", + }, + "debug-errors": "Common GraphQL over HTTP Errors", } diff --git a/src/pages/learn/best-practices.mdx b/src/pages/learn/best-practices.mdx index 5c9b5527d4..7cf153a6af 100644 --- a/src/pages/learn/best-practices.mdx +++ b/src/pages/learn/best-practices.mdx @@ -53,5 +53,10 @@ The articles in this section should not be taken as gospel, and in some cases ma link: "/learn/security/", description: "Protect GraphQL APIs from malicious operations", }, + { + title: "Common Errors", + link: "/learn/debug-errors/", + description: "Learn about common `graphql-http` errors and how to debug them.", + } ]} /> diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx new file mode 100644 index 0000000000..5fbd65d499 --- /dev/null +++ b/src/pages/learn/debug-errors.mdx @@ -0,0 +1,157 @@ +# Common HTTP Errors and How to Debug Them + +When building or consuming a GraphQL API over HTTP, it's common to run into +errors, especially during development. Understanding how to recognize and resolve these issues +can save you time and frustration. + +This guide outlines common HTTP and GraphQL errors, what they mean, and how to debug them +effectively. It follows the recommendations of the +[GraphQL over HTTP spec (draft)](https://graphql.github.io/graphql-over-http/draft/), +which standardizes how GraphQL works over HTTP, including request formats, status codes, +and media types. Keep in mind that implementations may vary, so treat this as a general guide rather +than a definitive reference. + +## `400 Bad Request`: Syntax or parse errors + +### What it means + +The server couldn't parse your request. Either the GraphQL query string is malformed, +or the JSON body isn't valid. + +### Common causes + +- JSON syntax errors +- Sending a plain string without wrapping it in `{ "query": "..." }` +- Using `Content-Type: application/graphql` without supporting it + +### How to debug + +- Validate your JSON body using a linter or formatter. +- Make sure you're sending a `POST` request with a `Content-Type: application/json` header. +- Check your GraphQL query for syntax errors. Use an IDE or linter to verify it. + +## `405 Method Not Allowed`: Wrong HTTP Method + +### What it means + +You're using an unsupported HTTP method. Most GraphQL servers require `POST` for mutations +and may allow `GET` for queries. + +### Common causes + +- Sending a `PUT` or `DELETE` request instead of `POST` or `GET` +- Sending a `GET` request for a mutation, or to a server that only supports `POST` requests + +### How to debug + +- Check your HTTP method. Mutations must use `POST`. +- Make sure your server supports `GET` for queries. +- Refer to the [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/draft/) to +confirm method support. + +## `415 Unsupported Media Type` + +### What it means + +The server doesn't understand the request's `Content-Type`. + +### Common causes + +- Sending a GraphQL query with `Content-Type: text/plain` or another unsupported type +- Omitting the `Content-Type` header in a `POST` request + +### How to debug + +- Set the header explicitly: `Content-Type: application/json`. +- If you're using `application/graphql`, verify your server supports it. This content type +is optional. + +## `422 Unprocessable Entity`: Missing or invalid `query` + +### What it means + +The server received the request, but the `query` field was missing or invalid. + +### Common causes + +- Sending `{}` with no `query` key +- Sending variables or an operation name without a query + +### How to debug + +Always include a `query` field in your request body. For example: + +```json +{ + "query": "{ user(id: 1) { name } }" +} +``` + +## `500 Internal Server Error`: Unexpected server failures + +### What it means + +Something went wrong on the server. + +### Common causes + +- An unhandled exception in a resolver +- Schema validation issues during server startup +- Missing or misconfigured middleware + +### How to debug + +- Check server logs or stack traces. +- Add error handling to resolvers. + +## GraphQL errors with `200 OK` + +### What it means + +The HTTP layer succeeded, but the GraphQL operation produced errors. + +### Common causes + +- Querying a field that doesn't exist +- Passing incorrect arguments to a field +- Violating schema constraints, such as non-nullability +- Runtime errors during execution + +### How to debug + +Check the `errors` array in the response body. If the response includes a `data` property, then +your query document is likely valid and you most likely hit a runtime exception - perhaps due to +invalid input, access denial, or a bug in server logic. + +If there's no `data` field, the request likely failed during validation. For example: + +```json +{ + "errors": [ + { + "message": "Cannot query field \"foo\" on type \"Query\".", + "locations": [{ "line": 1, "column": 3 }] + } + ] +} +``` + +Use introspection or an IDE to verify your query matches the schema. + +## Understanding GraphQL response formats + +Most GraphQL servers return responses using the `application/json` media type. However, +the [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/draft/) recommends +using a more specific type: `application/graphql-response+json`. + +This media type identifies the payload as a GraphQL response and helps clients +distinguish it from other types of JSON. + +### What to know + +- Servers may respond with `application/graphql-response+json` instead of +`application/json`. +- Clients can request this media type using the `Accept` header: `Accept: application/graphql-response+json` +- This content type is optional, but support for it is growing. +- If your client uses content negotiation, ensure your server can response with the appropriate +type or fallback to `application/json`.