錯誤代碼

本頁面列出您透過通用商務通訊協定 (UCP) 與 Google 整合時，必須在 API 回應中傳回的標準錯誤代碼。一致的錯誤代碼可確保溝通清楚明瞭，並協助 Google 適當處理不同情況。

發生商家錯誤時，API 應傳回包含表格中適當 code 的回應訊息。對於某些錯誤代碼，建議在回應的 messages 陣列中使用特定 JSON 結構。這些範例位於下方表格的「錯誤代碼範例」一節。在這些範例中，您應使用 path 欄位，提供要求或回應物件中錯誤位置的更具體資訊。

處理錯誤

回報錯誤的方式取決於錯誤類型：

  • 通訊協定/伺服器錯誤：

    • 針對要求格式錯誤、驗證失敗或伺服器無法使用等問題，使用標準 HTTP 狀態碼 (例如：用戶端錯誤為 4xx，伺服器錯誤為 5xx)。
    • 詳情請參閱 UCP 規格。

  • 商業邏輯錯誤/警告：

    • 傳回 HTTP 200 OK 狀態。包括付款遭拒和詐欺拒絕，即使下游付款閘道傳回 4xx 或 5xx 錯誤也一樣。
    • 在 JSON 回應主體的 messages 陣列中說明問題。
    • messages 陣列中的每個物件都必須包含：
      • type："error" 或 "warning"
      • code：本指南中的標準化代碼。請勿使用通用或無法辨識的代碼，例如 "invalid"。
      • content：使用者可自然閱讀的說明。
      • severity：type 為 "error" 時為必要。這個欄位會明確指出錯誤是否為終端錯誤 (unrecoverable)，或讓您提示買家修正問題 (recoverable)，而非依據錯誤代碼本身。

訊息類型：錯誤與警告

訊息陣列中的 type 欄位會指出問題的嚴重程度。UCP 定義了兩種主要類型：

  • error：表示無法完成要求的作業。 平台或使用者可能需要採取行動，然後再試一次。請參閱訊息錯誤規格。
    • 錯誤的終端性質取決於 severity 欄位 (unrecoverable 或 recoverable)，而非錯誤 code。
  • warning：表示作業未遭到封鎖，但有值得向使用者傳達的資訊。這不會停止程序，但會提供重要背景資訊。請參閱訊息警告規格。

錯誤代碼參考資料

錯誤代碼 建議類型 說明
out_of_stock 錯誤 無法取得這個項目。這通常會導致 ucp.status: “error”。在多項商品結帳時，請使用 path 欄位指出商品索引。請參閱下方範例。
item_unavailable 錯誤 找不到項目。這通常會導致這些項目相關錯誤的 ucp.status: “error”。
item_ineligible 錯誤 項目存在，但無法使用 UCP 購買。
quantity_invalid_limit_exceeded 錯誤 要求的數量超出允許上限。請參閱下方範例。
quantity_invalid_minimum_not_met 錯誤 要求的數量低於最低要求。
totals_changed 警告 價格或其他總計金額自上一步驟後有所變更。使用 path 欄位指出變更的總計。請參閱下方範例。
totals_invalid_minimum_not_met 錯誤 訂單價值未達最低要求。
missing_buyer_info 錯誤 缺少必要的買家資訊。使用 path 欄位指定缺少的欄位。請參閱下方範例。
address_undeliverable 錯誤 這是標準 UCP 錯誤代碼。使用 path 欄位指出特定目的地或受限商品。請參閱下方範例。
address_unverifiable 錯誤 無法驗證提供的地址。使用 path 欄位指出這是出貨地址還是帳單地址。請參閱下方範例。
missing_fulfillment_info 錯誤 缺少必要的出貨資訊。使用 path 欄位指定缺少的欄位。
eligibility_invalid 錯誤 使用者或訂單不符合執行動作的資格。這是標準 UCP 錯誤代碼。如要瞭解具體資訊，請使用 path 欄位。
discount_code_invalid 警告 折扣碼無效。找不到代碼或代碼格式錯誤。
discount_code_expired 警告 折扣碼已過期。
discount_code_already_applied 警告 折扣碼已套用。
discount_code_combination_disallowed 警告 折扣碼不得與其他優惠合併使用。
discount_code_user_not_logged_in 警告 使用者必須登入才能使用折扣碼。
discount_code_user_ineligible 警告 使用者不符合折扣代碼的使用資格。
missing_billing_info 錯誤 缺少必要的帳單資訊。使用 path 欄位指定缺少的帳單地址欄位。請參閱下方範例。
identity_required 錯誤 要求執行的作業需要使用者身分，但系統未提供、無效、過期或無法驗證。如果是 REST，請使用狀態碼 401。請參閱下方範例。
insufficient_scope 錯誤 使用者身分權杖有效，但缺少作業所需的範圍。如果是 REST，請使用狀態碼 403。請參閱下方範例。
payment_declined 錯誤 發卡機構或銀行拒絕付款。原因可能包括資金不足、疑似詐欺或卡片問題。請參閱下方範例。
payment_failed 錯誤 處理期間發生技術問題 (例如網路錯誤、閘道逾時或整合問題)，導致銀行無法做出決定，因此付款失敗。
payment_ineligible 錯誤 系統不接受所選付款方式。適用於使用者需要嘗試其他付款方式的情況。
rejected_for_fraud 錯誤 訂單疑似有詐欺行為，因此遭到拒絕。請參閱下方範例。

錯誤代碼範例

本節提供特定錯誤代碼的 messages 陣列 JSON 範例。

out_of_stock

單一商品結帳：

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

多項商品結帳：

使用 path 欄位指出缺貨商品的索引。

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

quantity_invalid_limit_exceeded

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

totals_changed

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

missing_buyer_info

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

address_undeliverable

訂單層級限制 (例如不支援郵遞區號)：

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

項目層級限制：

使用 path 欄位，指出無法運送至所選目的地的特定商品 (例如州級禁令)。

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

address_unverifiable

帳單地址：

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

出貨地址：

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

missing_billing_info

使用 path 欄位指定帳單地址中缺少的欄位。

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

identity_required

在 REST API 中，這項錯誤應以 HTTP 狀態碼 401 傳回。

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

insufficient_scope

在 REST API 中，這項錯誤應以 HTTP 狀態碼 403 傳回。

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

付款錯誤

payment_declined

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}

rejected_for_fraud

{
  "type": "error",
  "severity": "recoverable",
  "code": "rejected_for_fraud",
  "path": "$.payment.instruments[0]",
  "content": "The order was rejected due to suspected fraud. Try a different payment method."
}