處理錯誤回應

本指南說明如何處理 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 物件提供有關錯誤的穩定結構化資料：

domain：錯誤的邏輯分組，通常是 merchantapi.googleapis.com。
metadata：與錯誤相關的動態價值對應。包括：
- 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：這類錯誤通常是暫時性的。以指數輪詢方式重試。

如何聯絡 Merchant API 支援團隊

如需就特定錯誤與 Merchant API 支援團隊聯絡，請在要求中提供下列資訊：

收到的確切錯誤回應
API 方法名稱
要求酬載
呼叫方法和收到錯誤的時間戳記或日期範圍

Track usage metrics

Error messages