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 プロトコルが含まれていることがよくあります。

各 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.v25.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 が含まれます。
トレーリングメタデータ: 成功したリクエストと失敗したリクエストの両方で、request-id は gRPC レスポンスのトレーリングメタデータで使用できます。
レスポンスヘッダー: 成功したリクエストと失敗したリクエストの両方で、成功したストリーミングリクエストを除き、gRPC レスポンスヘッダーと HTTP レスポンスヘッダーで request-id も使用できます。
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 秒待機します。再試行の最大回数または合計待機時間に達するまで続けます。
- ジッター: バックオフ遅延に小さなランダムな「ジッター」を追加して、多くのクライアントが同時に再試行する「サンダリングハード」の問題を防ぎます。
詳細なログを記録する: すべての詳細（特にリクエスト ID）を含む完全なエラーレスポンスを記録します。この情報は、デバッグや、必要に応じて Google サポートに問題を報告する際に不可欠です。
ユーザーフィードバックを提供する: 特定の GoogleAdsError コードとメッセージに基づいて、アプリのユーザーに明確で役立つフィードバックを提供します。たとえば、「エラーが発生しました」ではなく、「キャンペーン名が必要です」や「指定された広告グループ ID が見つかりませんでした」と表示します。

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

エラータイプ

よくある間違い

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