错误代码

本页面概述了在使用通用商务协议 (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：表示无法完成所请求的操作。 平台或用户可能需要采取行动，然后重试。请参阅message-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."
}