错误类型

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

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

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

  • 常见错误提供了有关特定错误的更多详细信息。
  • 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 错误