處理錯誤回應

本指南說明如何處理 Merchant API 傳回的錯誤。瞭解錯誤回應結構和穩定性，對於建構強大的整合功能至關重要，因為這類功能可自動從失敗中復原，或向使用者提供有意義的意見回饋。

總覽

如果 Merchant API 要求失敗，API 會傳回標準 HTTP 狀態碼 (4xx 或 5xx)，以及包含錯誤詳細資料的 JSON 回應本文。Merchant API 遵循 AIP-193 標準提供錯誤詳細資料，提供機器可讀取的資訊，讓應用程式以程式輔助方式處理特定錯誤情境。

。

錯誤回應結構

錯誤回應是 JSON 物件，內含 code、message 和 status 等標準欄位。最重要的是，其中也包含 details 陣列。如要透過程式輔助方式處理錯誤，請在 details 中尋找 @type 為 type.googleapis.com/google.rpc.ErrorInfo 的物件。

這個 ErrorInfo 物件提供穩定的錯誤結構化資料：

  • 網域：錯誤的邏輯分組，通常為 merchantapi.googleapis.com。
  • 中繼資料：與錯誤相關的動態值對應。包括：
    • REASON：特定錯誤的穩定 ID (例如 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：特定錯誤 ID。應用程式的控制流程邏輯應依賴這個欄位。

    • details.metadata 鍵：中繼資料對應中的鍵 (例如FIELD_LOCATION、ACCOUNT_IDS) 現已穩定。
    • code：高階 HTTP 狀態碼 (例如 400、401、503) 現已穩定。

  • 不穩定的欄位：

    • message：使用者可理解的錯誤訊息不穩定。僅供開發人員偵錯。請勿編寫會剖析或依賴 message 欄位文字內容的程式碼，因為該欄位可能會在未事先通知的情況下變更，以提升清楚程度或新增背景資訊。
    • details.metadata 值：鍵是穩定的，但資訊鍵的值可能會變更。舉例來說，如果提供 HELP_CENTER_LINK 鍵，系統可能會在未事先通知的情況下，將該鍵指向的特定網址更新為較新的說明文件頁面。不過，如先前所述，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. 方法呼叫期間和收到錯誤的時間戳記或時間範圍