Google 広告のサービスに関するご意見やご提案は、Google 広告と測定のコミュニティサーバーの公式 Google 広告 Discord チャンネルにご参加ください。

このページは Cloud Translation API によって翻訳されました。

API エラーについて

このガイドでは、Google Ads API でエラーを処理して通知する方法について説明します。API エラーの構造と意味を理解することは、無効な入力から一時的なサービス停止まで、問題を適切に処理できる堅牢なアプリケーションを構築するうえで重要です。

Google Ads API は、gRPC ステータスコードに基づく標準の Google API エラーモデルに従います。エラーが発生した各 API レスポンスには、次の情報を含む Status オブジェクトが含まれます。

数値のエラーコード。
エラーメッセージ。
省略可。エラーに関する追加の詳細。

標準的なエラーコード

Google Ads API では、gRPC と HTTP で定義された一連の正規のエラーコードを使用します。これらのコードは、エラーの種類を大まかに示します。問題の根本的な性質を理解するには、まずこの数値コードを確認する必要があります。

次の表に、Google Ads API の使用時に発生する可能性のある最も一般的なコードをまとめます。

gRPC コード	HTTP コード	列挙型の名前	説明	ガイダンス
0	200	`OK`	エラーなし。成功を示します。	なし
1	499	`CANCELLED`	オペレーションがキャンセルされました。通常、キャンセルはクライアントにより行われます。	通常は、クライアントが待機を停止したことを意味します。クライアントサイドのタイムアウトを確認します。
2	500	`UNKNOWN`	不明なエラーが発生しました。エラーメッセージまたは詳細に、詳細情報が記載されている場合があります。	サーバーエラーとして扱います。多くの場合、バックオフで再試行できます。
3	400	`INVALID_ARGUMENT`	クライアントが無効な引数を指定しました。これは、リソース名が正しくない、値が無効であるなど、API がリクエストを処理できない問題を示します。	クライアントエラー: リクエストパラメータを確認し、API 要件を満たしていることを確認します。通常、エラーの詳細には、どの引数が無効であったか、どのように無効であったかに関する情報が示されます。これらの詳細を使用して、リクエストを修正します。リクエストを修正してから再試行します。
4	504	`DEADLINE_EXCEEDED`	オペレーションが完了する前に期限が切れました。	サーバーエラー: 一時的なエラーであることが多い。指数バックオフを使用して再試行することを検討してください。
5	404	`NOT_FOUND`	リクエストされたエンティティ（キャンペーンや広告グループなど）が見つかりませんでした。	クライアントエラー: アクセスしようとしているリソースの存在と ID を確認します。修正せずに再試行しないでください。
6	409	`ALREADY_EXISTS`	クライアントが作成しようとしたエンティティはすでに存在します。	クライアントエラー: 重複するリソースの作成を避けます。リソースを作成する前に、リソースが存在するかどうかを確認します。
7	403	`PERMISSION_DENIED`	呼び出し元には、指定されたオペレーションを実行する権限がありません。	クライアントエラー: Google 広告アカウントの認証、承認、ユーザーロールを確認します。権限を解決せずに再試行しないでください。
8	429	`RESOURCE_EXHAUSTED`	リソースが枯渇している（割り当てを超過しているなど）か、システムが過負荷になっています。	クライアント/サーバーエラー: 通常、待機が必要です。指数バックオフを実装し、リクエストレートを減らす。API の制限と割り当てをご覧ください。
9	400	`FAILED_PRECONDITION`	システムがオペレーションの実行に必要な状態ではないため、オペレーションが拒否されました。たとえば、必須項目が指定されていない場合などです。	クライアントエラー: リクエストは有効ですが、状態が正しくありません。エラーの詳細を確認して、前提条件の失敗を理解します。状態を修正せずに再試行しないでください。
10	409	`ABORTED`	オペレーションは、通常、トランザクションの競合などの同時実行の問題のために中止されました。	サーバーエラー: 短いバックオフで再試行しても安全な場合が多い。
11	400	`OUT_OF_RANGE`	オペレーションが有効な範囲を超えて試行されました。	クライアントエラー: 範囲またはインデックスを修正します。
12	501	`UNIMPLEMENTED`	オペレーションが実装されていないか、API でサポートされていません。	クライアントエラー: API バージョンと利用可能な機能を確認します。再試行しないでください。
13	500	`INTERNAL`	内部エラーが発生しました。これは、サーバーサイドの問題の一般的な包括的なカテゴリです。	サーバーエラー: 通常は指数バックオフで再試行できます。問題が解決しない場合は、問題を報告してください。
14	503	`UNAVAILABLE`	サービスは現在使用できません。これは一時的な状態である可能性が高く、	サーバーエラー: 指数バックオフで再試行することを強くおすすめします。
15	500	`DATA_LOSS`	回復不能なデータの消失や破損。	サーバーエラー: まれ。重大な問題を示します。再試行しないでください。問題が解決しない場合は、問題を報告してください。
16	401	`UNAUTHENTICATED`	リクエストに有効な認証情報がありません。	クライアントエラー: 認証トークンと認証情報を確認します。認証を修正してから再試行します。

これらのコードの詳細については、API 設計ガイド - エラーコードをご覧ください。

エラーの詳細を理解する

最上位のコード以外に、Google Ads API は Status オブジェクトの details フィールド内でより具体的なエラー情報を提供します。このフィールドには、個々の GoogleAdsError オブジェクトのリストを含む GoogleAdsFailure プロトコルが含まれていることがよくあります。

各 GoogleAdsFailure オブジェクトには次の要素が含まれます。

errors: 発生した特定のエラーの詳細を示す GoogleAdsError オブジェクトのリスト。
request_id: リクエストの一意の ID。デバッグやサポートに役立ちます。

各 GoogleAdsError オブジェクトは次のものを提供します。

errorCode: Google Ads API 固有のエラーコード（AuthenticationError.NOT_ADS_USER など）。
message: 特定のエラーに関する人が読める形式の説明。
trigger: エラーの原因となった値（該当する場合）。
location: エラーが発生したリクエスト内の場所（フィールドパスを含む）を説明します。
details: 未公開のエラー理由などのエラーの詳細。

エラーの詳細の例

エラーが発生すると、クライアントライブラリを使用してこれらの詳細にアクセスできます。たとえば、INVALID_ARGUMENT（コード 3）には次のような GoogleAdsFailure の詳細が含まれる場合があります。

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

この例では、トップレベルの INVALID_ARGUMENT にもかかわらず、GoogleAdsFailure の詳細から、name フィールドと description フィールドが問題の原因であることと、その理由（それぞれ REQUIRED と TOO_SHORT）がわかります。

エラーの詳細を確認する

エラーの詳細にアクセスする方法は、標準 API 呼び出し、部分的な失敗、ストリーミングのいずれを使用しているかによって異なります。

標準 API 呼び出しとストリーミング API 呼び出し

部分的な失敗を使用せずに API 呼び出しが失敗した場合（ストリーミング呼び出しを含む）、GoogleAdsFailure オブジェクトは gRPC レスポンスヘッダーのトレーリングメタデータの一部として返されます。標準呼び出しに REST を使用している場合、HTTP レスポンスで GoogleAdsFailure が返されます。クライアントライブラリは通常、これを GoogleAdsFailure 属性を持つ例外として表面化します。

部分的な失敗

部分的な失敗を使用している場合、失敗したオペレーションのエラーはレスポンスヘッダーではなく、レスポンスの partial_failure_error フィールドで返されます。この場合、GoogleAdsFailure はレスポンスの google.rpc.Status オブジェクト内に埋め込まれます。

バッチジョブ

バッチ処理の場合、個々のオペレーションのエラーは、ジョブの完了後にバッチジョブの結果を取得することで確認できます。オペレーションが失敗した場合、各オペレーション結果にはエラーの詳細を含む status フィールドが含まれます。

リクエスト ID

request-id は、API リクエストを識別する一意の文字列で、トラブルシューティングに不可欠です。

request-id は次の場所にあります。

GoogleAdsFailure: API 呼び出しが失敗し、GoogleAdsFailure が返された場合、request_id が含まれます。
トレーリングメタデータ: 成功したリクエストと失敗したリクエストの両方で、gRPC レスポンスのトレーリングメタデータで request-id を使用できます。
レスポンスヘッダー: 成功したリクエストと失敗したリクエストの両方で、成功したストリーミングリクエストを除き、gRPC と HTTP のレスポンスヘッダーでも request-id を使用できます。
SearchGoogleAdsStreamResponse: ストリーミングリクエストの場合、各 SearchGoogleAdsStreamResponse メッセージには request_id フィールドが含まれます。

エラーをログに記録したり、サポートに連絡したりする場合は、問題の診断に役立つように request-id を含めてください。

エラー処理のベストプラクティス

復元力のあるアプリケーションを構築するには、次のベストプラクティスを実装します。

エラーの詳細を検査する: Status オブジェクトの details フィールドを常に解析し、特に GoogleAdsFailure を探します。GoogleAdsError 内のきめ細かい errorCode、message、location は、デバッグとユーザーフィードバックに最も役立つ情報を提供します。
クライアントエラーとサーバーエラーを区別します。
- クライアントエラー: INVALID_ARGUMENT、NOT_FOUND、PERMISSION_DENIED、FAILED_PRECONDITION、UNAUTHENTICATED などのコード。これらには、リクエストまたはアプリケーションの状態/認証情報の変更が必要です。問題を解決せずにリクエストを再試行しないでください。
- サーバーエラー: UNAVAILABLE、INTERNAL、DEADLINE_EXCEEDED、UNKNOWN などのコード。これは、API サービスの一時的な問題を示しています。
再試行戦略を実装します。
- 再試行のタイミング: UNAVAILABLE、DEADLINE_EXCEEDED、INTERNAL、UNKNOWN、ABORTED などの一時的なサーバーエラーの場合にのみ再試行します。
- 指数バックオフ: 指数バックオフのアルゴリズムを使用して、再試行の間の待ち時間を徐々に増やします。これにより、すでに負荷がかかっているサービスにさらに負荷がかかるのを防ぐことができます。たとえば、1 秒待ってから 2 秒待ち、4 秒待つというように、再試行の最大回数または合計待機時間に達するまで続けます。
- ジッター: バックオフ遅延に小さなランダムな「ジッター」を追加して、多くのクライアントが同時に再試行する「サンダリングハード」の問題を防ぎます。
ログを徹底的に記録する: エラーレスポンスのすべての詳細（特にリクエスト ID）を含む完全なログを記録します。この情報は、デバッグや、必要に応じて Google サポートに問題を報告する際に不可欠です。
ユーザーフィードバックを提供する: 特定の GoogleAdsError コードとメッセージに基づいて、アプリのユーザーに明確で役立つフィードバックを提供します。たとえば、「エラーが発生しました」ではなく、「キャンペーン名が必要です」や「指定された広告グループ ID が見つかりませんでした」とします。

これらのガイドラインに沿って対応することで、Google Ads API から返されるエラーを効果的に診断して処理し、より安定したユーザーフレンドリーなアプリケーションを実現できます。

API エラーについて コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。