错误类型
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
我们将错误分为以下几大类：
虽然这些类别并未穷尽所有可能的错误，并且某些错误可划归于一个以上的类别，但仍可从这里着手来设计应用的错误处理机制。如需详细了解特定错误，请参阅以下资源：
身份验证错误
所谓身份验证，指的是您的应用是否已获得用户授予的、可代表他们访问 Google Ads 的权限。身份验证的管理是通过 OAuth2 流程生成的凭据实现的。
身份验证错误可能是由您无法控制的因素导致的，其中最常见的一个原因是经过身份验证的用户撤消了他们向您的应用授予的代表他们执行操作的权限。例如，如果您的应用为多个独立客户分别管理不同的 Google Ads 账号，并在管理每个客户的账号时分别以该客户的身份接受身份验证，则客户随时都可能撤消您应用的访问权限。这种情况下 API 可能会直接返回一个 AuthenticationError.OAUTH_TOKEN_REVOKED 错误，或者客户端库中的内置凭据对象可能会引发令牌被撤消异常，具体取决于您的访问权限被撤消的时间。无论在哪种情况下，如果您的应用为客户提供了界面，就可以要求他们重新启动 OAuth2 流程，以重建您的应用代表他们进行操作的权限。
可重试错误
有些错误（如 TRANSIENT_ERROR 或 INTERNAL_ERROR）可能是临时性问题所致，可通过在短时间暂停后重试请求来解决。
对于用户发起的请求，一种策略是立即在界面中指出错误，并为用户提供进行重试的选项。另一种策略是，您的应用先自动重试请求，只有在达到最大重试次数或用户总等待时间后才在界面中指出错误。
对于后端发起的请求，您的应用应该自动重试请求，直到达到最大重试次数。
重试请求时，请使用指数退避策略。例如，如果您在第一次重试前先暂停 5 秒，则可以在第二次重试后暂停 10 秒，在第三次后暂停 20 秒。指数退避有助于确保您不会过于频繁地调用 API。
验证错误
验证错误表示操作的输入不可接受。
例如，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 错误应该会促使您的应用在本地数据库中将相应广告标记为已移除。无法以这种方式处理的错误可能会导致您的应用启动更完整的同步作业，或者被添加到队列中供操作员审核。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-27。
[null,null,["最后更新时间 (UTC)：2025-08-27。"],[[["\u003cp\u003eGoogle Ads API errors are categorized into Authentication, Retryable, Validation, and Sync-related errors for easier handling.\u003c/p\u003e\n"],["\u003cp\u003eAuthentication errors often stem from revoked user permissions and can be resolved by re-initiating the OAuth2 flow.\u003c/p\u003e\n"],["\u003cp\u003eRetryable errors, like \u003ccode\u003eTRANSIENT_ERROR\u003c/code\u003e or \u003ccode\u003eINTERNAL_ERROR\u003c/code\u003e, can be addressed with exponential backoff retry strategies.\u003c/p\u003e\n"],["\u003cp\u003eValidation errors arise from unacceptable input and require providing specific error messages to users or queuing for review.\u003c/p\u003e\n"],["\u003cp\u003eSync-related errors indicate discrepancies between your local data and Google Ads, necessitating data refreshes or sync jobs.\u003c/p\u003e\n"]]],[],null,["# Error Types\n\nWe've categorized errors into the following broad categories:\n\n- Authentication\n- Retryable\n- Validation\n- Sync-related\n\nThough these categories don't encompass all possible errors, and\nsome may fit into more than one category, they can nevertheless serve as\na starting point for structuring your app's error handling. See the following\nresources for more details about specific errors:\n\n- [Common Errors](/google-ads/api/docs/common-errors) provides more details about a particular error.\n- [google.rpc.Status](/google-ads/api/reference/rpc/google.rpc#status) for details about the logical error model used by the API.\n\nAuthentication errors\n---------------------\n\nAuthentication refers to whether your app has been given permission by a user to\naccess Google Ads on their behalf. Authentication is managed through\ncredentials generated by the [OAuth2 flow](/google-ads/api/docs/oauth/overview).\n\nThe most common reason an authentication error arises from factors beyond your\ncontrol is that the authenticated user has revoked the permission they gave your\napp to act on their behalf. For example, if your app manages separate Google Ads\naccounts for independent clients and authenticates separately as each client\nwhen managing that client's account, a client could revoke your app's access at\nany time. Depending on when your access was revoked, the API may directly return\nan `AuthenticationError.OAUTH_TOKEN_REVOKED` error, or the built-in credential\nobjects in the [Client Libraries](/google-ads/api/docs/client-libs) may throw a\ntoken revoked exception. In either case, if your app has a UI for your clients,\nit could ask them to relaunch the OAuth2 flow to reestablish your app's\npermission to act on their behalf.\n\nRetryable errors\n----------------\n\nSome errors, such as [`TRANSIENT_ERROR`](/google-ads/api/reference/rpc/v21/InternalErrorEnum.InternalError#transient_error)\nor [`INTERNAL_ERROR`](/google-ads/api/reference/rpc/v21/InternalErrorEnum.InternalError#internal_error),\ncan indicate a temporary problem that may be resolved by retrying the\nrequest after a short pause.\n\nFor user-initiated requests, one strategy is to immediately indicate an error in\nyour UI and give the user an option to trigger a retry. Alternatively, your app\ncould first automatically retry the request, only exposing the error in the UI\nafter reaching a maximum number of retries or total user wait time.\n\nFor requests initiated on the back end, your app should automatically retry the\nrequest up to a maximum number of retries.\n\nWhen you retry requests, use an exponential backoff policy. For example, if you\nfirst pause 5 seconds before the first retry, you could pause 10 seconds after\nthe second and 20 seconds after the third retry. Exponential backoff helps\nensure you are not calling the API too aggressively.\n\nValidation errors\n-----------------\n\nValidation errors indicate that an input to an operation was not acceptable.\nFor example, [`PolicyViolationError`](/google-ads/api/reference/rpc/v21/PolicyViolationErrorEnum.PolicyViolationError),\n[`DateError`](/google-ads/api/reference/rpc/v21/DateErrorEnum.DateError),\n[`DateRangeError`](/google-ads/api/reference/rpc/v21/DateRangeErrorEnum.DateRangeError),\n[`StringLengthError`](/google-ads/api/reference/rpc/v21/StringLengthErrorEnum.StringLengthError), and\n[`UrlFieldError`](/google-ads/api/reference/rpc/v21/UrlFieldErrorEnum.UrlFieldError).\n\nValidation errors occur most commonly in user-initiated requests, where a user\nhas entered invalid input. In these cases, you should provide an appropriate\nerror message to the user based on the specific API error you received. You can\nalso validate user input for common mistakes before making an API call, making\nyour app more responsive and your API usage more efficient. For requests from\nthe back end, your app could add the failed operation to a queue\nfor a human operator to review.\n\nSync-related errors\n-------------------\n\nMany Google Ads apps maintain a local database to store their Google Ads objects. One\nchallenge to this approach is that the local database may go out of sync with\nthe actual objects in Google Ads. For example, a user might delete an ad group\ndirectly in Google Ads, but the app and local database are unaware of the change and\ncontinue to issue API calls as if the ad group existed. These sync issues can\nmanifest as a variety of errors such as [`DUPLICATE_CAMPAIGN_NAME`](/google-ads/api/reference/rpc/v21/CampaignErrorEnum.CampaignError#duplicate_campaign_name),\n[`DUPLICATE_ADGROUP_NAME`](/google-ads/api/reference/rpc/v21/AdGroupErrorEnum.AdGroupError#duplicate_adgroup_name),\n[`AD_NOT_UNDER_ADGROUP`](/google-ads/api/reference/rpc/v21/AdGroupAdErrorEnum.AdGroupAdError#ad_not_under_adgroup),\n[`CANNOT_OPERATE_ON_REMOVED_ADGROUPAD`](/google-ads/api/reference/rpc/v21/AdGroupAdErrorEnum.AdGroupAdError#cannot_operate_on_removed_adgroupad),\nand many others.\n\nFor user-initiated requests, one strategy is to alert the user to a possible\nsync problem, immediately launch a job that retrieves the relevant class of\nGoogle Ads objects and updates the local database, then prompt the user to refresh\nthe UI.\n\nFor back-end requests, some errors provide enough information for your\napp to automatically and incrementally correct your local database. For example,\n[`CANNOT_OPERATE_ON_REMOVED_ADGROUPAD`](/google-ads/api/reference/rpc/v21/AdGroupAdErrorEnum.AdGroupAdError#cannot_operate_on_removed_adgroupad)\nshould cause your app to mark that ad as\nremoved in your local database. Errors that you cannot handle in this way could\ncause your app to launch a more complete sync job or be added to a queue for a\nhuman operator to review."]]
