API エラーの処理

Google Ads API にリクエストを送信すると、さまざまな理由で失敗することがあります。たとえば、無効な引数を指定した場合や、アカウントで新しいキャンペーンを作成できる上限に達した場合などです。このような場合、API はエラーを返して、何が問題だったかを通知します。

このガイドでは、API エラーを読み取って処理し、より堅牢なアプリケーションを構築する方法について説明します。

エラーの構造

クライアント ライブラリのいずれかを使用している場合、API エラーは例外として表示されます。これらの例外には、エラーが発生した理由を理解するのに役立つ詳細が含まれています。

Google Ads API は、標準形式でエラー情報を返します。エラーが発生した場合、レスポンスには GoogleAdsFailure オブジェクトが含まれます。このオブジェクトには、個々の GoogleAdsError オブジェクトのリストが含まれています。各オブジェクトは特定のエラーの詳細を示します。

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

  • error_code: エラーの種類を示す特定のエラーコード（AuthenticationError.NOT_ADS_USER など）。
  • message: エラーが発生した理由に関する説明（人が読める形式）。
  • trigger: エラーの原因となった値（「1234」など）。
  • location: リクエストのどの部分がエラーの原因となったかについての詳細（特定のフィールド名など）。

エラーのリストに加えて、GoogleAdsFailure には requestId が含まれています。これは、エラーが発生した API リクエストの一意の識別子です。

エラーの例

JSON 形式のエラーの例を次に示します。このエラーは、インデックス 0 の ad_group の name フィールドがリクエストにないことを示します。

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

エラーの処理方法

エラーが発生した場合は、次の手順を行います。

  1. errors リストを調べる: GoogleAdsFailure オブジェクトの各 GoogleAdsError を確認します。error_code と message で、何が問題だったかを確認できます。
  2. location を確認する: location フィールドは、リクエストのどこで問題が発生したかを特定するのに役立ちます。
  3. ドキュメントを参照する: 特定のエラーコードについては、一般的なエラーのページまたはエラーコードのリファレンスで、エラーの詳細と修正方法をご確認ください。
  4. リクエストを調整する: エラー メッセージに基づいて、API リクエストを修正します。たとえば、REQUIRED_FIELD_MISSING が表示された場合は、リクエストでそのフィールドを指定してください。
  5. request_id をログに記録する: エラーの解決方法がわからず、フォーラムを通じてサポートに連絡する必要がある場合は、request_id を含めてください。この ID は、Google のエンジニアが問題を調査する際に役立ちます。

次のステップ

  • よくある問題とその解決策については、一般的なエラーをご覧ください。
  • 再試行ロジックや部分的な障害など、より高度なエラー処理手法については、API エラーについてをご覧ください。
前へ
クイックスタート
次へ
よくある間違い