docs: add guide on graphql-http errors

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-http` Errors",
 }

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.",
+    }
   ]}
 />

src/pages/learn/debug-errors.mdx

@@ -0,0 +1,134 @@
+# Common `graphql-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 `graphql-http` errors, what they mean, and how to debug them 
+effectively. These examples assume you're using the 
+[GraphQL over HTTP specification](https://graphql.github.io/graphql-over-http/draft/)
+and an implementation such as [`graphql-http`](https://github.com/graphql/graphql-http) or any 
+server that follows the spec.
+
+## `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.
+- Verify that the GraphQL query is syntactically correct. Use an IDE or a 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
+
+### 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 response contains errors.
+
+### Common causes
+
+- Querying a field that doesn't exist
+- Passing incorrect arguments to a field
+- Violating schema constraints, such as non-nullability
+
+### How to debug
+
+Check the `errors` array in the response body. A typical response looks like:
+
+```json
+{
+  "data": null,
+  "errors": [
+    {
+      "message": "Cannot query field \"foo\" on type \"Query\".",
+      "locations": [{ "line": 1, "column": 3 }]
+    }
+  ]
+}
+```
+
+Compare your query against the schema using introspection or an IDE.