错误类型

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

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

虽然这些类别并未穷尽所有可能的错误,并且某些错误可划归于一个以上的类别,但仍可从这里着手来设计应用的错误处理机制。有关特定错误的更多详细信息,请参阅常见错误

身份验证错误

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

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

可重试错误

有些错误(例如 TRANSIENT_ERRORINTERNAL_ERROR)可能表示暂时性问题,可通过在短时间暂停后重试请求来解决。

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

对于后端发起的请求,您的应用应该自动重试请求,直到达到最大重试次数。

重试请求时,请使用指数退避策略。例如,如果您在第一次重试前先暂停 5 秒,则可以在第二次重试后暂停 10 秒,在第三次后暂停 20 秒。指数退避有助于确保您不会过于频繁地调用 API。

验证错误

验证错误表示操作的输入不可接受。例如,PolicyViolationErrorDateErrorDateRangeErrorStringLengthErrorUrlFieldError

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

许多 Google Ads 应用都会维护一个本地数据库,用于存储其 Google Ads 对象。这种方法会遇到一个难题,就是本地数据库可能与 Google Ads 中的实际对象不同步。例如,用户可能直接在 Google Ads 中删除了广告组,但应用和本地数据库不知道有此更改并继续发出 API 调用,以为那个广告组仍存在一样。这些同步问题可以表现为各种错误,例如 DUPLICATE_CAMPAIGN_NAMEDUPLICATE_ADGROUP_NAMEAD_NOT_UNDER_ADGROUPCANNOT_OPERATE_ON_REMOVED_ADGROUPAD 等等。

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

对于后端发起的请求,某些错误会提供充足的信息,供您的应用逐步自动更正您的本地数据库。例如,CANNOT_OPERATE_ON_REMOVED_ADGROUPAD 会导致您的应用在本地数据库中将相应广告标记为已移除。无法以这种方式处理的错误可能会导致您的应用启动更完整的同步作业,或者被添加到队列中供操作员审核。