Skip to content

docs: add guide on graphql-http errors #2006

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Jun 19, 2025
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fix: remove 415 and 422 and add disclaimer
  • Loading branch information
sarahxsanders committed Jun 10, 2025
commit 176d140cf82c3e5d294a3d275c265e74b4c5824a
52 changes: 13 additions & 39 deletions src/pages/learn/debug-errors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ than a definitive reference.
### What it means

The server couldn't parse your request. Either the GraphQL query string is malformed,
or the JSON body isn't valid.
or the JSON body isn't valid. This is the primary error status recommended by the GraphQL over HTTP specification.

### Common causes

Expand Down Expand Up @@ -49,44 +49,6 @@ and may allow `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
Expand Down Expand Up @@ -138,6 +100,18 @@ If there's no `data` field, the request likely failed during validation. For exa

Use introspection or an IDE to verify your query matches the schema.

## Implementation-specific status codes

Some GraphQL server implementations may use additional HTTP status codes that are not explicitly recommended
by the specification. These vary by implementation.

- `415 Unsupported Media Type`: The server doesn't understand the request's `Content-Type`. This can occur
when a GraphQL query is sent with `Content-Type: text/plain` or another unsupported type.
- `422 Unprocessable Entity`: Some implementations use this for GraphQL validation errors instead of `200` + errors array.

These error codes are not recommended by the specification for most cases. Different GraphQL servers handle
validation errors differently. When in doubt, use error codes supported by the specification.

## Understanding GraphQL response formats

Most GraphQL servers return responses using the `application/json` media type. However,
Expand Down