了解 API 错误

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

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

• 数字错误代码。
• 错误消息。
• 可选，其他错误详情。

规范错误代码

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

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

gRPC 代码	HTTP 代码	枚举名称	说明	指南
0	200	OK	无错误；表示成功。	不适用
1	499	CANCELLED	操作已取消（通常是被客户端取消）。	通常表示客户端停止等待。检查客户端超时。
2	500	UNKNOWN	发生未知错误。出错提示或详细信息中可能包含更多详情。	视为服务器错误。通常可以使用退避算法重试。
3	400	INVALID_ARGUMENT	客户端指定的参数无效。这表示存在导致 API 无法处理请求的问题，例如资源名称格式不正确或值无效。	客户端错误：请检查您的请求参数，确保其符合 API 要求。错误详情通常会提供有关哪个参数无效以及如何无效的信息，请使用这些详情来修正请求。在修正请求之前，请勿重试。
4	504	DEADLINE_EXCEEDED	在操作完成之前截止期限已过。	服务器错误：通常是暂时性的。考虑使用指数退避算法重试。
5	404	NOT_FOUND	找不到所请求的部分实体，例如广告系列或广告组。	客户端错误：请验证您尝试访问的资源是否存在，并检查其 ID。在未更正的情况下，请勿重试。
6	409	ALREADY_EXISTS	客户端尝试创建的实体已存在。	客户端错误：避免创建重复资源。在尝试创建资源之前，请先检查该资源是否存在。
7	403	PERMISSION_DENIED	调用方无权执行指定的操作。	客户端错误：请检查 Google Ads 账号的身份验证、授权和用户角色。在解决权限问题之前，请勿重试。
8	429	RESOURCE_EXHAUSTED	资源已用尽（例如，您已超出配额），或者系统过载。	客户端/服务器错误：通常需要等待。实现指数退避算法，并可能降低请求速率。请参阅 API 限制和配额。
9	400	FAILED_PRECONDITION	操作被拒绝，因为系统未处于执行该操作所需的状态。例如，缺少必填字段。	客户端错误：请求有效，但 state 错误。查看错误详情，了解前提条件失败的原因。在未更正状态的情况下，请勿重试。
10	409	ABORTED	操作已中止，通常是由于事务冲突等并发问题。	服务器错误：通常可以安全地在短暂退避后重试。
11	400	OUT_OF_RANGE	尝试执行的操作已超出有效范围。	客户端错误：请更正范围或索引。
12	501	UNIMPLEMENTED	该操作未实现或不受 API 支持。	客户端错误：请检查 API 版本和可用功能。不重试。
13	500	INTERNAL	发生内部错误。这是服务器端问题的通用统称。	服务器错误：通常可以使用指数退避算法重试。如果问题仍然存在，请报告问题。
14	503	UNAVAILABLE	服务暂时不可用。这很可能是暂时性情况。	服务器错误：强烈建议使用指数退避算法重试。
15	500	DATA_LOSS	数据丢失或损坏且不可恢复。	服务器错误：罕见。表示存在严重问题。不重试。如果问题仍然存在，请报告问题。
16	401	UNAUTHENTICATED	请求没有有效的身份验证凭证。	客户端错误：验证您的身份验证令牌和凭据。在解决身份验证问题之前，请勿重试。

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

了解错误详情

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

每个 GoogleAdsFailure 对象都包含：

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

每个 GoogleAdsError 对象都提供：

• error_code：更精细、Google Ads API 专用的 ErrorCode（常见错误），例如 AuthenticationError.NOT_ADS_USER。
• message：特定错误的人类可读说明。
• trigger：导致错误的 Value（如果适用）。
• location：一个 ErrorLocation，用于描述请求中发生错误的位置，包括字段路径。
• details：其他 ErrorDetails，例如未发布错误原因。

错误详情示例

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

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

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

查找错误详情

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

标准和流式 API 调用

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

部分失败

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

批量作业

对于批量处理，可以在作业完成后调用 BatchJobService.ListBatchJobResults 来查找各个操作的错误。如果操作失败，每个操作结果都将包含一个 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 中的精细 error_code、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 返回的错误，从而打造更稳定、更人性化的应用。