エラータイプ

エラーは大まかに以下のカテゴリに分けられます。

  • 認証
  • 再試行可能なエラー
  • 検証
  • 同期関連

これらのカテゴリは、考えられるすべてのエラーを網羅しているわけではなく、複数のカテゴリに該当するエラーもありますが、アプリのエラー処理を構築する際の出発点として役立ちます。特定のエラーの詳細については、次のリソースをご覧ください。

  • 一般的なエラーでは、特定のエラーの詳細を確認できます。
  • google.rpc.Status には、API で使用されるロジックエラーモデルの詳細が記載されています。
  • 正規のエラーコードでは、Google Ads API のコンテキストで gRPC と HTTP によって定義された正規のエラーコードのリストと説明を提供します。

認証エラー

認証とは、アプリケーションがユーザーに代わって Google 広告にアクセスして処理する権限を、ユーザーが許可することです。認証は、OAuth2 フローによって生成された認証情報によって管理されます。

認証エラーの制御不能な原因で最も多いのは、認証したユーザーがアプリケーションに許可した代理権限を取り消した場合です。たとえば、アプリケーションでクライアントのアカウントを管理する際に、独立したクライアント別に Google 広告アカウントを管理し、クライアントごとに認証を受けている場合、各クライアントはアプリケーションのアクセス権をいつでも取り消すことができます。アクセスが取り消されたタイミングによっては、API が AuthenticationError.OAUTH_TOKEN_REVOKED エラーを直接返すか、クライアント ライブラリの組み込み認証情報オブジェクトがトークン取り消し例外をスローすることがあります。いずれの場合も、アプリにクライアント用の UI がある場合は、OAuth2 フローを再起動して、アプリがクライアントの代わりに操作する権限を再確立するようクライアントに求めることができます。

関連して、Google Cloud プロジェクトにテスト アクセスレベルしかなく、本番環境（テスト以外）のアカウントに対してリクエストを送信しようとすると、API は AuthorizationError を返します。この列挙値は API のバージョンによって異なります。

再試行可能なエラー

TRANSIENT_ERROR や INTERNAL_ERROR などの一部のエラーは、一時的な問題を示している可能性があります。この問題は、少し待ってからリクエストを再試行することで解決できます。

ユーザーが開始するリクエストの場合、すぐに UI にエラーを表示し、ユーザーに再試行する選択肢を示す方法が考えられます。また、最初はアプリケーションでリクエストを自動的に再試行し、再試行の最大回数に達するか、一定の合計ユーザー待機時間が経過して初めて UI にエラーを表示するという方法も考えられます。

バックエンドで開始されたリクエストの場合、アプリは最大再試行回数までリクエストを自動的に再試行する必要があります。

リクエストを再試行する場合は、ランダム化されたジッターを含む指数バックオフ ポリシーを使用します。たとえば、最初の再試行の前に 5 秒間一時停止する場合は、2 回目の再試行後に 10 秒間、3 回目の再試行後に 20 秒間一時停止し、各間隔に小さなランダムな遅延を追加して、同期された再試行の急増を防ぐことができます。指数バックオフは、API を過度に呼び出さないようにするのに役立ちます。再試行を繰り返してもエラーが解決しない場合は、トラブルシューティングのためにレスポンスから request-id をログに記録します。

検証エラー

検証エラーは、オペレーションへの入力が受け入れられなかったことを示します。たとえば、PolicyViolationError、DateError、DateRangeError、StringLengthError、UrlFieldError などがあります。

検証エラーは、ユーザーが開始するリクエストで入力内容が無効であった場合に最も多く発生します。この場合、受け取った API エラーに応じて、適切なエラー メッセージをユーザーに示す必要があります。API を呼び出す前にユーザー入力のよくある間違いを検証することで、アプリケーションの応答時間を短縮し、より効率的に API を使用することもできます。バックエンドからのリクエストの場合、アプリは失敗したオペレーションをキューに追加して、人間のオペレーターが確認できるようにします。

Google 広告 アプリの多くにはローカル データベースがあり、Google 広告 オブジェクトが保存されています。このアプローチの課題の 1 つは、ローカル データベースが 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 を受け取った場合、アプリはローカル データベースでその広告を削除済みとしてマークする必要があります。この方法で処理できないエラーが発生した場合、アプリはより完全な同期ジョブを起動するか、人間のオペレーターが確認できるようにキューに追加します。

次へ
API エラーについて