エラー レスポンスを処理する

このガイドでは、Merchant API から返されるエラーの処理方法について説明します。 エラー レスポンスの構造と安定性を理解することは、障害から自動的に復旧したり、ユーザーに有益なフィードバックを提供したりできる堅牢な統合を構築するうえで非常に重要です。

概要

Merchant API リクエストが失敗すると、API は標準の HTTP ステータス コード（4xx または 5xx）と、エラーの詳細を含む JSON レスポンス本文を返します。 Merchant API は、エラーの詳細に AIP-193 標準に準拠しており、アプリケーションが特定のエラー シナリオをプログラムで処理できるように、機械可読な情報を提供します。

エラー レスポンスの構造

エラー レスポンスは、code, message、および status などの標準フィールドを含む JSON オブジェクトです。重要な点として、details 配列も含まれています。エラーをプログラムで処理するには、details 内で @type が type.googleapis.com/google.rpc.ErrorInfo のオブジェクトを探します。

この ErrorInfo オブジェクトは、エラーに関する安定した構造化データを提供します。

  • domain: エラーの論理グループ。通常は merchantapi.googleapis.com。
  • metadata: エラーに関連する動的な値のマップ。これには、次のものが含まれます。
    • REASON: 正確なエラーの特定の安定した識別子（例: INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS)。この フィールドは常に存在します。アプリケーション ロジックでこのフィールドを使用して、きめ細かいエラー処理を行います。
    • HELP_CENTER_LINK: 問題を解決するための追加のコンテキストと手順を 提供します。このフィールドはすべてのエラーに存在するわけではありませんが、より多くのコンテキストが必要になる可能性があるエラーについては、今後範囲を拡大する予定です。
    • その他の動的フィールド: 無効なフィールドの名前（FIELD_LOCATION）やエラーの原因となった値（FIELD_VALUE）など、コンテキストを提供するその他のキー。

エラー レスポンスの例

次の JSON は、リソース名が不正な形式の場合の Merchant API エラーの構造を示しています。

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

認証エラーの例を次に示します。

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

エラー フィールドの安定性

エラー処理ロジックを作成する際は、どのフィールドに依存しても安全で、どのフィールドが変更される可能性があるかを知ることが重要です。

  • 安定したフィールド:

  • details.metadata.REASON: 特定のエラー識別子。アプリケーションの制御フロー ロジックでは、このフィールドに依存する必要があります。

    • details.metadata キー: メタデータ マップ内のキー（FIELD_LOCATION、ACCOUNT_IDS など）は安定しています。
    • code: 高レベルの HTTP ステータス コード（400、401、503） は安定しています。

  • 不安定なフィールド:

    • message: 人が読めるエラー メッセージは安定していません。**デベロッパーのデバッグのみを目的としています。`message` フィールドのテキスト コンテンツを解析したり、それに依存したりするコードは記述しないでください。明確化やコンテキストの追加のために予告なく変更される可能性があります。
    • details.metadata 値: キーは安定していますが、情報キーの値 は変更される可能性があります。たとえば、HELP_CENTER_LINK キーが指定されている場合、そのキーが指す特定の URL は、事前の通知なしに新しいドキュメント ページに更新される可能性があります。ただし、前述のように、details.metadata.REASON の値は安定しています。

ベスト プラクティス

統合でエラーを適切に処理するには、次のおすすめの方法に従ってください。

ロジックに details.metadata.REASON を使用する

エラーの原因を特定するには、常に metadata マップ内の特定の REASON を使用します。複数のエラーで同じステータス コードが共有される可能性があるため、HTTP ステータス コードのみに依存しないでください。

エラー メッセージを解析しない

安定性のセクションで説明したように、message フィールドは人間が使用するためのものです。 無効なフィールドなど、動的な情報が必要な場合は、FIELD_LOCATION、VARIABLE_NAME などの安定したキーを使用して、metadata マップから抽出します。

指数バックオフを実装する

一時的な利用不可やレート制限を示すエラーの場合は、指数バックオフ戦略を実装します。つまり、再試行する前に短い期間待機し、後続の失敗ごとに待機時間を増やします。

  • quota/request_rate_too_high: このエラーは、特定の割り当てグループの分 単位の割り当てを超えたことを示します。リクエスト率を遅くしてください。
  • internal_error: 通常は一時的なものです。指数バックオフで再試行してください。注: バックオフで複数回再試行しても internal_error が解消されない場合は、Merchant API サポートへのお問い合わせ方法をご覧ください。

Merchant API サポートへのお問い合わせ方法

特定のエラーについて Merchant API サポートに問い合わせる必要がある場合は、リクエストに次の情報を含めてください。

  1. 受信した正確なエラー レスポンス
  2. API メソッドの名前
  3. リクエストのペイロード
  4. メソッドが呼び出され、エラーが受信されたタイムスタンプまたは時間範囲