排查响应错误

本页介绍如何排查 API 请求响应中返回的错误。

Upstream backend unavailable

如果您收到错误代码 14 和消息 upstream backend unavailable，这表示 Extensible Service Proxy (ESP) 无法访问服务的后端。请检查以下各项：

  • 确保后端服务正在运行。具体的操作方法取决于后端。

  • 已为后端服务指定正确的 IP 地址端口：
    • 对于 GKE，检查部署清单文件（通常称为 deployment.yaml）中的 ESP --backend 标志值（短选项为 -a）。
    • 对于 Compute Engine，检查 docker run 命令中的 ESP --backend 标志值（短选项为 -a）。

reset reason: connection failure

如果您收到 HTTP 代码 503 或 gRPC 代码 14 和消息 upstream connect error or disconnect/reset before headers. reset reason: connection failure，这表示 ESPv2 无法访问服务的后端。

如要进行问题排查，请仔细检查以下各项内容。

后端地址

您应使用正确的后端地址配置 ESPv2。常见问题包括：

  • 后端地址方案应与后端应用类型相匹配。OpenAPI 后端应为 http://，而 gRPC 后端应为 grpc://。
  • 对于部署在 Cloud Run 上的 ESPv2，后端地址方案应为 https:// 或 grpcs://。s 指示 ESPv2 使用后端设置 TLS。

DNS 查找

默认情况下，ESPv2 会尝试将域名解析为 IPv6 地址。如果 IPv6 解析失败，ESPv2 会回退为 IPv4 地址。

对于某些网络，后备机制可能无法按预期运行。您可以改为通过 --backend_dns_lookup_family 标志强制 ESPv2 使用 IPv4 地址。

如果您为 Cloud Run 上部署的 ESPv2 配置无服务器 VPC 连接器，则此错误很常见。VPC 不支持 IPv6 流量。

API is not enabled for the project

如果您在请求中发送了 API 密钥，但收到类似“没有为项目启用 API my-api.endpoints.example-project-12345.cloud.goog”的错误消息，则表示 API 密钥是在与 API 不同的 Google Cloud 项目中创建的。如需解决此问题，您可以在与 API 关联的同一 Google Cloud 项目中创建 API 密钥，也可以在创建了 API 密钥的 Google Cloud 项目中启用 API。

Service control request failed with HTTP response code 403

如果您收到错误代码 14 和消息 Service control request failed with HTTP response code 403，这表示该项目未启用 Service Control API (servicecontrol.googleapis.com)。

  1. 请参阅检查所需服务，确保在项目中启用了 Endpoints 和 ESP 所需的所有服务。

  2. 请参阅检查所需权限，以确保与运行 ESP 的实例关联的服务账号所需的所有权限。

Method doesn't allow unregistered callers

如果您在 gRPC API 配置文件中指定了 allow_unregistered_calls: false，但是向 API 发送的请求中未包含分配给名为 key 的查询参数的 API 密钥，则 ESP 会返回错误 Method doesn't allow unregistered callers 作为响应。

如果您需要生成 API 密钥以调用 API，请参阅创建 API 密钥。

Method does not exist

响应 Method does not exist 意味着在指定网址路径上找不到 HTTP 方法（GET、POST 或其他）。如需排查此问题，请比较已部署的服务配置，确保方法名称与您在请求中发送的网址路径匹配：

  1. 在 Google Cloud 控制台中，前往项目的 Endpoints 服务页面。

    转到“Endpoints 服务”页面

  2. 如果您有多个 API，请选择您向其发送了请求的 API。

  3. 点击部署记录标签。

  4. 选择最新的部署以查看服务配置。

Transport is closing

如果您收到错误代码 13 和消息 transport is closing，这表示 ESP 无法访问。

检查 ESP 错误日志。具体的操作方法取决于后端。 请参阅以下内容了解详细信息：

异常响应

如果 HTTP 响应看起来是二进制内容，这可能表明该请求正使用 HTTP2 端口调用 API，而您打算使用的是 HTTP1 端口。

检查 ESP 的端口配置选项。因为短式标志 -p（对于 HTTP1）和 -P（对于 HTTP2）看起来类似，我们建议您改用长式标志：对 HTTP1 使用 --http_port，对 HTTP2 使用 --http2_port。

ESP 后端配置错误也可能导致响应异常。确保将后端标志（-a 或 --backend）设置为 gRPC 网址，例如 --backend=grpc://127.0.0.1:8081。

如需详细了解 ESP 标志，请参阅 ESP 启动选项。

检查 Cloud Logging 日志

如需借助 Cloud 日志来排查响应错误，请执行以下操作：

  1. 在 Google Cloud 控制台中，转到 Logging 页面。

    转到“日志浏览器”页面

  2. 在页面顶部，选择 Google Cloud 项目。

  3. 使用左侧下拉菜单，选择 Produced API > [YOUR_SERVICE_NAME]。

  4. 调整时间范围，直到出现显示相关响应错误的行。

  5. 展开 JSON 载荷并查找 error_cause。

    • 如果 error_cause 设置为 application，这表示代码中存在问题。

    • 如果 error cause 为其他内容，并且您无法解决问题，请导出日志并将其附在您与 Google 的通信中。

请参阅以下内容了解详细信息：