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

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

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

概要

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

エラーレスポンスの構造

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

この 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 サポートにお問い合わせいただく場合は、リクエストに次の情報をご提供ください。

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

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

概要

エラー レスポンスの構造

エラー レスポンスの例

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

ベスト プラクティス

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

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