错误类型

我们将错误分为以下几大类：

  • 身份验证
  • 可重试的错误
  • 验证
  • 与同步相关

虽然这些类别并未涵盖所有可能的错误，并且某些错误可能属于多个类别，但它们仍可作为构建应用错误处理的起点。如需详细了解特定错误，请参阅以下资源：

  • 常见错误提供了有关特定错误的更多详细信息。
  • google.rpc.Status 提供了有关 API 使用的逻辑错误模型的详细信息。
  • 规范错误代码提供了 Google Ads API 上下文中由 gRPC 和 HTTP 定义的规范错误代码的列表和说明。

身份验证错误

所谓身份验证，指的是您的应用是否已获得用户授予的、可代表他们访问 Google Ads 的权限。身份验证通过 OAuth2 流程生成的凭据进行管理。

身份验证错误可能是由您无法控制的因素导致的，其中最常见的一个原因是经过身份验证的用户撤消了他们向您的应用授予的代表他们执行操作的权限。例如，如果您的应用为多个独立客户分别管理不同的 Google Ads 账号，并在管理每个客户的账号时分别以该客户的身份接受身份验证，则客户随时都可能撤消您应用的访问权限。根据您的访问权限被撤消的时间，API 可能会直接返回 AuthenticationError.OAUTH_TOKEN_REVOKED 错误，或者客户端库中的内置凭据对象可能会抛出令牌已撤消异常。在上述任一情况下，如果您的应用具有面向客户的界面，则可以要求客户重新启动 OAuth2 流程，以重新建立应用代表他们执行操作的权限。

与此相关的是，如果您的 Google Cloud 项目仅具有测试访问权限级别，并尝试针对生产（非测试）账号发出请求，则 API 会返回 AuthorizationError，其枚举值取决于 API 版本：

可重试的错误

某些错误（例如 TRANSIENT_ERROR 或 INTERNAL_ERROR）可能表示存在临时问题，在短暂暂停后重试请求可能会解决该问题。

对于用户发起的请求，一种策略是立即在界面中指出错误，并为用户提供进行重试的选项。另一种策略是，您的应用先自动重试请求，只有在达到最大重试次数或用户总等待时间后才在界面中指出错误。

对于在后端发起的请求，您的应用应自动重试请求，直至达到重试次数上限。

重试请求时，请使用具有随机抖动的指数退避算法政策。例如，如果您在第一次重试前暂停 5 秒，则可以在第二次重试后暂停 10 秒，在第三次重试后暂停 20 秒，并在每个间隔中添加一个小的随机延迟，以防止同步重试高峰。指数退避算法有助于确保您不会过于频繁地调用 API。如果错误在重试次数用尽后仍然存在，请记录响应中的 request-id 以进行问题排查。

验证错误

验证错误表示操作的输入不可接受。 示例包括 PolicyViolationError、DateError、DateRangeError、StringLengthError 和 UrlFieldError。

验证错误最常发生的情况是，在用户发起的请求中包含无效的用户输入。在这些情况下，您应根据收到的具体 API 错误向用户提供适当的错误消息。您还可以在进行 API 调用之前验证用户输入中是否有常见错误，从而提高您的应用的响应能力，同时提高对 API 的使用效率。对于来自后端的请求，您的应用可以将失败的操作添加到队列中，供人工操作员审核。

许多 Google Ads 应用都会维护一个本地数据库，用于存储其 Google Ads 对象。这种方法面临的一个挑战是，本地数据库可能与 Google Ads 中的实际对象不同步。例如，用户可能会直接在 Google Ads 中删除某个广告组，但应用和本地数据库并不知道这一更改，并继续发出 API 调用，就像该广告组仍然存在一样。这些同步问题可能会表现为各种错误，例如 DUPLICATE_CAMPAIGN_NAME、DUPLICATE_ADGROUP_NAME、AD_NOT_UNDER_ADGROUP、CANNOT_OPERATE_ON_REMOVED_ADGROUPAD 等。

对于用户发起的请求，一种策略是提醒用户可能存在同步问题，立即启动一个作业来检索相关类别的 Google Ads 对象并更新本地数据库，然后提示用户刷新界面。

对于后端请求，某些错误会提供足够的信息，以便您的应用自动且增量地更正本地数据库。例如，CANNOT_OPERATE_ON_REMOVED_ADGROUPAD 应使您的应用在本地数据库中将该广告标记为已移除。您无法通过这种方式处理的错误可能会导致应用启动更完整的同步作业，或被添加到队列中供人工操作员审核。

下一页
了解 API 错误