学习教程基于 HTTP 的 GraphQL 的常见错误

常见 HTTP 错误及其调试方法

¥Common HTTP Errors and How to Debug Them

在通过 HTTP 构建或使用 GraphQL API 时，经常会遇到错误，尤其是在开发过程中。了解如何识别和解决这些问题可以节省你的时间和精力。

¥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.

本指南概述了常见的 HTTP 和 GraphQL 错误、它们的含义以及如何有效地调试它们。它遵循 GraphQL over HTTP 规范（草案） 的建议，GraphQL over HTTP 规范（草案） 规范了 GraphQL 在 HTTP 上的工作方式，包括请求格式、状态码和媒体类型。请记住，实现方式可能有所不同，因此请将此视为一般指南，而不是最终参考。

¥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), 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：语法或解析错误

¥400 Bad Request: Syntax or parse errors

它是什么含义

¥What it means

服务器无法解析你的请求。可能是 GraphQL 查询字符串格式错误，或者 JSON 正文无效。这是 GraphQL over HTTP 规范推荐的主要错误状态。

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

常见原因

¥Common causes

  • JSON 语法错误

    ¥JSON syntax errors

  • 发送未封装在 { "query": "..." } 中的纯字符串

    ¥Sending a plain string without wrapping it in { "query": "..." }

  • 使用不支持的 Content-Type: application/graphql 类型

    ¥Using Content-Type: application/graphql without supporting it

调试方法

¥How to debug

  • 使用代码检查工具或格式化工具验证你的 JSON 正文。

    ¥Validate your JSON body using a linter or formatter.

  • 请确保你发送的 POST 请求带有 Content-Type: application/json 标头。

    ¥Make sure you’re sending a POST request with a Content-Type: application/json header.

  • 检查 GraphQL 查询是否存在语法错误。使用 IDE 或代码检查工具进行验证。

    ¥Check your GraphQL query for syntax errors. Use an IDE or linter to verify it.

405 Method Not Allowed：HTTP 方法错误

¥405 Method Not Allowed: Wrong HTTP Method

它是什么含义

¥What it means

你正在使用不受支持的 HTTP 方法。大多数 GraphQL 服务器要求 mutation 操作使用 POST，查询操作可能使用 GET。

¥You’re using an unsupported HTTP method. Most GraphQL servers require POST for mutations and may allow GET for queries.

常见原因

¥Common causes

  • 发送 PUT 或 DELETE 请求，而不是 POST 或 GET 请求

    ¥Sending a PUT or DELETE request instead of POST or GET

  • 发送 GET 请求进行 mutation 操作，或发送到仅支持 POST 请求的服务器

    ¥Sending a GET request for a mutation, or to a server that only supports POST requests

调试方法

¥How to debug

  • 检查你的 HTTP 方法。mutation 操作必须使用 POST。

    ¥Check your HTTP method. Mutations must use POST.

  • 请确保你的服务器支持 GET 查询。

    ¥Make sure your server supports GET for queries.

  • 请参考 GraphQL over HTTP 规范 以确认方法支持情况。

    ¥Refer to the GraphQL over HTTP spec to confirm method support.

500 Internal Server Error：意外的服务器故障

¥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 错误（200 OK）

¥GraphQL errors with 200 OK

它是什么含义

¥What it means

HTTP 层成功，但 GraphQL 操作出现错误。

¥The HTTP layer succeeded, but the GraphQL operation produced errors.

常见原因

¥Common causes

  • 执行期间的运行时错误

    ¥Runtime errors during execution

  • 违反结构约束（例如，返回错误的数据类型，或在非空位置使用 null）。

    ¥Violating schema constraints (e.g. returning the wrong data type, or null in a non-nullable position)

较旧的服务器和客户端（不使用 Content-Type: application/graphql-response+json 的）在请求完全失败（不使用 data）的情况下，可能还会返回 200 OK。常见原因包括：

¥Older servers and clients (those not using Content-Type: application/graphql-response+json) may also use 200 OK in the case of complete request failure (no data). Common causes include:

  • 查询不存在的字段

    ¥Querying a field that doesn’t exist

  • 向字段传递错误的参数

    ¥Passing incorrect arguments to a field

  • 在非叶子字段上省略选择集

    ¥Omitting a selection set on a non-leaf field

  • 请求中存在多个操作时未指定 operationName

    ¥Failure to specify the operationName when multiple operations exist in the request

调试方法

¥How to debug

检查响应体中的 errors 数组。如果响应包含 data 属性，则你的查询文档很可能有效，并且你很可能遇到了运行时异常。 - 可能是由于输入无效、访问被拒绝或服务器逻辑中的错误造成的。

¥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.

如果没有 data 字段，则请求很可能在验证过程中失败。例如：

¥If there’s no data field, the request likely failed during validation. For example:

{
  "errors": [
    {
      "message": "Cannot query field \"foo\" on type \"Query\".",
      "locations": [{ "line": 1, "column": 3 }]
    }
  ]
}

使用内省或集成开发环境 (IDE) 来验证你的查询是否符合结构。

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

特定于实现的 HTTP 状态码

¥Implementation-specific status codes

某些 GraphQL 服务器实现可能会使用规范中未明确推荐的额外 HTTP 状态码。这些错误因实现而异。

¥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：服务器无法理解请求的 Content-Type。当 GraphQL 查询使用 Content-Type: text/plain 或其他不支持的类型发送时，可能会发生这种情况。

    ¥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：某些实现使用此状态码来表示 GraphQL 验证错误，而不是使用 200 + 错误数组。

    ¥422 Unprocessable Entity: Some implementations use this for GraphQL validation errors instead of 200 + errors array.

在大多数情况下，规范不建议使用这些错误代码。不同的 GraphQL 服务器处理验证错误的方式不同。如有疑问，请使用规范支持的错误代码。

¥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.

理解 GraphQL 响应格式

¥Understanding GraphQL response formats

传统上，GraphQL 服务器使用 application/json 媒体类型返回响应。但是，GraphQL over HTTP 规范 建议客户端请求（服务器响应）更具体的类型：application/graphql-response+json。

¥Traditionally, GraphQL servers have returned responses using the application/json media type. However, the GraphQL over HTTP spec recommends that clients request (and servers respond with) a more specific type: application/graphql-response+json.

这种较新的媒体类型将有效负载标识为 GraphQL 响应，并帮助客户端将其与其他类型的 JSON 区分开来，即使响应使用非 2xx 状态码，也可以安全地处理。可信代理、网关或其他中间机构可能会使用 JSON 描述错误，但除非是有效的 GraphQL 响应，否则绝不会使用 application/graphql-response+json。

¥This newer media type identifies the payload as a GraphQL response and helps clients distinguish it from other types of JSON, making the response safe to process even if it uses a non-2xx status code. A trusted proxy, gateway, or other intermediary might describe an error using JSON, but would never do so using application/graphql-response+json unless it was a valid GraphQL response.

须知

¥What to know

  • 服务器可能会响应 application/graphql-response+json 或 application/json 请求。

    ¥Servers may respond with application/graphql-response+json or application/json.

  • 客户端可以使用 Accept 标头请求此媒体类型：Accept: application/graphql-response+json, application/json;q=0.9（优先使用新媒体类型，但两者都接受）

    ¥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)

  • 推荐使用此内容类型，并且对其的支持正在不断增长。

    ¥This content type is recommended, and support for it is growing.

  • 如果你的客户端使用内容协商，请确保你的服务器能够响应适当的类型，或者回退到 application/json。

    ¥If your client uses content negotiation, ensure your server can response with the appropriate type or fallback to application/json.

联邦