エラータイプ

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

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

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

  • 一般的なエラーには、特定のエラーに関する詳細情報が記載されています。
  • 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 など、さまざまなエラーとして現れることがあります。

ユーザーが開始したリクエストの場合、考えられる戦略の 1 つは、同期の問題が発生する可能性があることをユーザーに警告し、関連するクラスの Google 広告オブジェクトを取得してローカル データベースを更新するジョブを直ちに起動し、UI を更新するようユーザーに促すことです。

バックエンド リクエストの場合、一部のエラーでは、アプリがローカル データベースを自動的に段階的に修正するのに十分な情報が提供されます。たとえば、CANNOT_OPERATE_ON_REMOVED_ADGROUPAD は、アプリがローカル データベースでその広告を削除済みとしてマークするようにします。この方法で処理できないエラーが発生すると、アプリがより完全な同期ジョブを開始したり、オペレーターが確認するためのキューに追加されたりする可能性があります。

次へ
API エラーについて