エラーの種類
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
エラーは大まかに以下のカテゴリに分けられます。
これらのカテゴリはすべてのエラーを網羅しているわけではなく、エラーによっては複数のカテゴリに当てはまるものもありますが、アプリケーションのエラー処理を構築する第一歩として役に立ちます。特定のエラーの詳細については、次のリソースをご覧ください。
認証エラー
認証とは、アプリケーションがユーザーに代わって Google 広告にアクセスして処理する権限を、ユーザーが許可することです。認証は、OAuth2 フローによって生成される認証情報を通じて管理されます。
認証エラーの制御不能な原因で最も多いのは、認証したユーザーがアプリケーションに許可した代理権限を取り消した場合です。たとえば、アプリケーションでクライアントのアカウントを管理する際に、独立したクライアント別に Google 広告アカウントを管理し、クライアントごとに認証を受けている場合、各クライアントはアプリケーションのアクセス権をいつでも取り消すことができます。アクセス権が取り消されたタイミングによっては、API から直接 AuthenticationError.OAUTH_TOKEN_REVOKED エラーが返されたり、クライアント ライブラリに組み込みの認証情報オブジェクトからトークン失効の例外がスローされたりする場合があります。いずれの場合も、アプリケーションにクライアント用の UI があれば、OAuth2 フローを再起動してアプリケーションの代理権限を再確立するよう、クライアントに求める設計にする方法が考えられます。
再試行可能なエラー
TRANSIENT_ERROR や INTERNAL_ERROR などのエラーには一時的な問題であり、少し待ってリクエストを再試行すれば解決できるものもあります。
ユーザーが開始するリクエストの場合、すぐに UI にエラーを表示し、ユーザーに再試行する選択肢を示す方法が考えられます。また、最初はアプリケーションでリクエストを自動的に再試行し、再試行の最大回数に達するか、一定の合計ユーザー待機時間が経過して初めて UI にエラーを表示するという方法も考えられます。
バックエンドで開始されるリクエストの場合、アプリケーションでリクエストを最大回数まで自動的に再試行する必要があります。
リクエストの再試行では、指数バックオフ ポリシーを使用します。たとえば、最初の再試行の前に 5 秒待機した場合、2 回目の前には 10 秒、3 回目には 20 秒待機するようにします。指数バックオフは、API の過剰な呼び出しを防ぐことに役立ちます。
検証エラー
検証エラーは、オペレーションへの入力が無効であることを示すエラーです。たとえば、PolicyViolationError、DateError、DateRangeError、StringLengthError、UrlFieldError などです。
検証エラーは、ユーザーが開始するリクエストで入力内容が無効であった場合に最も多く発生します。この場合、受け取った API エラーに応じて、適切なエラー メッセージをユーザーに示す必要があります。API を呼び出す前にユーザー入力のよくある間違いを検証することで、アプリケーションの応答時間を短縮し、より効率的に API を使用することもできます。バックエンドで開始されたリクエストの場合、失敗したオペレーションをキューに追加し、オペレーターが確認できるようにする方法が考えられます。
Google 広告アプリケーションの多くにはローカル データベースがあり、Google 広告オブジェクトが保存されています。この手法には、ローカル データベースと Google 広告にある実際のオブジェクトが同期しなくなる場合があるという問題があります。たとえば、ユーザーが Google 広告で直接広告グループを削除しても、アプリケーションとローカ ルデータベースがその変更を認識せず、広告グループが存在するかのように API 呼び出しを発行し続けます。このような同期の問題は、DUPLICATE_CAMPAIGN_NAME、DUPLICATE_ADGROUP_NAME、AD_NOT_UNDER_ADGROUP、CANNOT_OPERATE_ON_REMOVED_ADGROUPAD などのさまざまなエラーとして現れます。
ユーザーが開始するリクエストの場合、同期に問題がある可能性があることをユーザーに警告した直後に、Google 広告オブジェクトの関連クラスを取得してローカル データベースを更新するジョブを開始し、ユーザーに UI を更新するよう促す方法があります。
バックエンドで開始されるリクエストの場合、エラーによっては、提供される情報を使用して、アプリケーションが自動的にローカル データベースの増分を修正できます。たとえば、CANNOT_OPERATE_ON_REMOVED_ADGROUPAD を受け取ったら、アプリケーションで該当の広告をローカル データベースから削除するようにマークを付ける必要があります。この方法で処理できないエラーの場合、アプリケーションでより包括的な同期ジョブを開始するか、オペレーターが確認できるようエラーをキューに追加する方法が考えられます。
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2025-09-05 UTC。
[null,null,["最終更新日 2025-09-05 UTC。"],[[["\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."]]
