Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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 proto が含まれていることがよくあります。

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

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

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

error_code: より詳細な Google Ads API 固有の ErrorCode（一般的なエラー）。例: AuthenticationError.NOT_ADS_USER。
message: 特定のエラーに関する人が読める形式の説明。
trigger: エラーの原因となった Value（該当する場合）。
location: フィールドパスなど、リクエスト内でエラーが発生した場所を記述する ErrorLocation。
details: 追加の ErrorDetails（公開されていないエラーの理由など）。

エラーの詳細の例

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

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

この例では、最上位の 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 オブジェクト内に埋め込まれます。

バッチジョブ

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

リクエスト ID

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

request-id は、次の複数の場所で確認できます。

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

エラーをログに記録する場合や、サポートに問い合わせる場合は、問題の診断に役立つ request-id を含めてください。

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

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

エラーの詳細を調べる: 常に Status オブジェクトの details フィールドを解析し、特に GoogleAdsFailure を探します。GoogleAdsError 内の詳細な error_code、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 秒と待機し、再試行の最大回数または合計待機時間に達するまで待機を続けます。
- ジッター: バックオフ遅延に少量のランダムな「ジッター」を追加して、多くのクライアントが同時に再試行する「Thundering Herd」問題を回避します。
詳細なログを記録する: すべての詳細（特にリクエスト ID）を含む、エラーレスポンス全体をログに記録します。この情報は、デバッグや、必要に応じて Google サポートに問題を報告する際に不可欠です。
ユーザーフィードバックを提供する: 特定の GoogleAdsError コードとメッセージに基づいて、アプリケーションのユーザーに明確で有用なフィードバックを提供します。たとえば、「エラーが発生しました」ではなく、「キャンペーン名は必須です」や「指定された広告グループ ID が見つかりませんでした」とします。

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

エラータイプ

よくある間違い

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