了解 API 错误

本指南介绍了 Google Ads API 如何处理和传达错误。 了解 API 错误的结构和含义对于构建能够妥善处理各种问题的强大应用至关重要，这些问题包括输入无效和临时服务不可用等。

Google Ads API 遵循基于 gRPC 状态代码的标准 Google API 错误模型。导致错误的每个 API 响应都包含一个 Status 对象，其中包含：

• 一个数值错误代码。
• 错误消息。
• 可选，其他错误详细信息。

规范错误代码

Google Ads API 使用 gRPC 和 HTTP 定义的一组规范错误代码。这些代码可大致指明错误类型。您应始终先检查此数字代码，以了解问题的根本性质。

下表总结了使用 Google Ads API 时可能会遇到的一些最常见代码：

如需详细了解这些代码，请参阅 API 设计指南 - 错误代码。

了解错误详情

除了顶级代码之外，Google Ads API 还在 Status 对象的 details 字段中提供了更具体的错误信息。此字段通常包含 GoogleAdsFailure proto，其中包括各个 GoogleAdsError 对象的列表。

每个 GoogleAdsFailure 对象都包含：

• errors：GoogleAdsError 对象的列表，每个对象都详细说明了发生的特定错误。
• request_id：请求的唯一 ID，有助于进行调试和提供支持。

每个 GoogleAdsError 对象都提供：

• errorCode：更精细的 Google Ads API 特有的错误代码，例如 AuthenticationError.NOT_ADS_USER。
• message：具体错误的直观易懂的说明。
• trigger：导致错误的相应值（如果适用）。
• location：描述错误发生在请求中的何处，包括字段路径。
• details：其他错误详情，例如未发布的错误原因。

错误详情示例

当您收到错误时，客户端库将允许您访问这些详细信息。例如，INVALID_ARGUMENT（代码 3）可能具有如下所示的 GoogleAdsFailure 详细信息：

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

在此示例中，尽管顶级 INVALID_ARGUMENT，但 GoogleAdsFailure 详细信息会告知您 name 和 description 字段导致了问题以及原因（分别为 REQUIRED 和 TOO_SHORT）。

查找错误详情

您访问错误详情的方式取决于您使用的是标准 API 调用、部分失败还是流式传输。

标准 API 调用和流式 API 调用

如果 API 调用在不使用部分失败的情况下失败（包括流式传输调用），则 GoogleAdsFailure 对象会作为 gRPC 响应标头中尾部元数据的一部分返回。如果您使用 REST 进行标准调用，则会在 HTTP 响应中返回 GoogleAdsFailure。客户端库通常会通过带有 GoogleAdsFailure 属性的异常来显示此问题。

部分失败

如果您使用部分失败，则失败操作的错误会返回在响应的 partial_failure_error 字段中，而不是在响应标头中。在这种情况下，GoogleAdsFailure 嵌入在响应的 google.rpc.Status 对象中。

批处理作业

对于批处理，您可以在作业完成后检索批处理作业结果，以查找各个操作的错误。如果操作失败，每个操作结果都将包含一个 status 字段，其中包含错误详细信息。

请求 ID

request-id 是用于标识 API 请求的唯一字符串，对于问题排查至关重要。

您可以在多个位置找到 request-id：

• GoogleAdsFailure：如果 API 调用失败并返回 GoogleAdsFailure，则会包含 request_id。
• 尾部元数据：对于成功和失败的请求，request-id 都可在 gRPC 响应的尾部元数据中找到。
• 响应标头：对于成功和失败的请求，request-id 也可在 gRPC 和 HTTP 响应标头中使用，但成功的流式请求除外。
• SearchGoogleAdsStreamResponse：对于流式请求，每个 SearchGoogleAdsStreamResponse 消息都包含一个 request_id 字段。

在记录错误或与支持团队联系时，请务必附上 request-id，以便我们诊断问题。

错误处理最佳实践

如需构建弹性佳的应用，请遵循以下最佳实践：

1. 检查错误详情：始终解析 Status 对象的 details 字段，尤其要查找 GoogleAdsFailure。GoogleAdsError 中的精细 errorCode、message 和 location 可提供最实用的调试和用户反馈信息。

2. 区分客户端错误和服务器错误：

   • 客户端错误：代码如 INVALID_ARGUMENT、NOT_FOUND、PERMISSION_DENIED、FAILED_PRECONDITION、UNAUTHENTICATED。这些错误需要更改请求或应用的状态/凭据。 在解决问题之前，请勿重试请求。
   • 服务器错误：例如 UNAVAILABLE、INTERNAL、DEADLINE_EXCEEDED、UNKNOWN 等代码。这表明 API 服务存在暂时性问题。

3. 实现重试策略：

   • 何时重试：仅针对临时服务器错误（例如 UNAVAILABLE、DEADLINE_EXCEEDED、INTERNAL、UNKNOWN 和 ABORTED）重试。
   • 指数退避：使用指数退避算法来等待越来越长的时间，然后再重试。这有助于避免使已承受压力的服务不堪重负。例如，等待 1 秒，然后等待 2 秒，再等待 4 秒，以此类推，直至达到重试次数上限或总等待时间上限。
   • 抖动：在退避延迟时间中添加少量随机“抖动”，以防止出现“惊群”问题，即许多客户端同时重试。

4. 记录完整：记录完整的错误响应，包括所有详细信息，尤其是请求 ID。此信息对于调试至关重要，并且在需要时可用于向 Google 支持团队报告问题。

5. 提供用户反馈：根据具体的 GoogleAdsError 代码和消息，向应用的用户提供清晰且有用的反馈。例如，您可以显示“需要提供广告系列名称”或“找不到提供的广告组 ID”，而不是仅显示“发生了错误”。

遵循这些准则，您可以有效地诊断和处理 Google Ads API 返回的错误，从而打造更稳定且更易于使用的应用。