Mã lỗi

Trang này trình bày các mã lỗi chuẩn mà bạn phải trả về trong các phản hồi của API khi tích hợp với Google bằng Giao thức thương mại toàn cầu (UCP). Mã lỗi nhất quán đảm bảo thông tin liên lạc rõ ràng và giúp Google xử lý các tình huống khác nhau một cách phù hợp.

Khi xảy ra lỗi về doanh nghiệp, API của bạn sẽ trả về một thông báo phản hồi bao gồm code thích hợp trong bảng. Đối với một số mã lỗi, bạn nên dùng một cấu trúc JSON cụ thể cho mảng messages trong phản hồi. Các ví dụ này được cung cấp trong phần Ví dụ về mã lỗi bên dưới bảng. Trong những ví dụ này, bạn nên sử dụng trường path để cung cấp thông tin cụ thể hơn về vị trí của lỗi trong đối tượng yêu cầu hoặc phản hồi.

Xử lý lỗi

Cách báo cáo lỗi tuỳ thuộc vào loại lỗi:

  • Lỗi giao thức/máy chủ:

    • Sử dụng mã trạng thái HTTP tiêu chuẩn (ví dụ: 4xx cho lỗi máy khách, 5xx cho lỗi máy chủ) đối với các vấn đề như yêu cầu không đúng định dạng, lỗi xác thực hoặc máy chủ không hoạt động.
    • Tham khảo Quy cách UCP để biết thông tin chi tiết.

  • Lỗi/Cảnh báo về logic nghiệp vụ:

    • Trả về trạng thái HTTP 200 OK. Điều này bao gồm cả trường hợp thanh toán bị từ chối và trường hợp gian lận bị từ chối, ngay cả khi cổng thanh toán hạ nguồn của bạn trả về lỗi 4xx hoặc 5xx.
    • Mô tả vấn đề trong mảng messages trong phần nội dung phản hồi JSON.
    • Mỗi đối tượng trong mảng messages phải chứa:
      • type: "error" hoặc "warning"
      • code: Một mã tiêu chuẩn trong hướng dẫn này. Đừng sử dụng các mã chung chung hoặc không được nhận dạng như "invalid".
      • content: Nội dung mô tả mà con người có thể đọc được.
      • severity: Bắt buộc khi type là "error". Trường này cho biết rõ ràng liệu lỗi có phải là lỗi nghiêm trọng (unrecoverable) hay cho phép bạn nhắc người mua sửa vấn đề (recoverable), thay vì dựa vào chính mã lỗi.

Các loại thông báo: Lỗi so với cảnh báo

Trường type trong mảng thông báo cho biết mức độ nghiêm trọng của vấn đề. UCP xác định 2 loại chính:

  • error: Cho biết rằng không thể hoàn tất thao tác được yêu cầu. Nền tảng hoặc người dùng có thể cần thực hiện hành động và thử lại. Xem quy cách message-error.
    • Bản chất cuối cùng của một lỗi được xác định bằng trường severity (unrecoverable hoặc recoverable), chứ không phải lỗi code.
  • warning: Cho biết rằng thao tác không bị chặn, nhưng có điều gì đó đáng chú ý cần truyền đạt cho người dùng. Điều này không làm dừng quy trình mà cung cấp bối cảnh quan trọng. Xem quy cách message-warning.

Tham chiếu mã lỗi

Mã lỗi Loại được đề xuất Mô tả
out_of_stock Lỗi Mặt hàng không có sẵn. Điều này thường dẫn đến ucp.status: “error”. Sử dụng trường path để cho biết chỉ mục của mặt hàng trong quy trình thanh toán nhiều mặt hàng. Hãy xem ví dụ bên dưới.
item_unavailable Lỗi Không tìm thấy mục. Điều này thường dẫn đến ucp.status: “error” đối với những lỗi liên quan đến mặt hàng này.
item_ineligible Lỗi Mặt hàng tồn tại nhưng không thể mua bằng UCP.
quantity_invalid_limit_exceeded Lỗi Số lượng bạn yêu cầu vượt quá giới hạn cho phép. Hãy xem ví dụ bên dưới.
quantity_invalid_minimum_not_met Lỗi Số lượng được yêu cầu thấp hơn số lượng tối thiểu bắt buộc.
totals_changed Cảnh báo Giá hoặc các khoản tổng cộng khác đã thay đổi kể từ bước gần đây nhất. Sử dụng trường path để cho biết tổng số nào đã thay đổi. Hãy xem ví dụ bên dưới.
totals_invalid_minimum_not_met Lỗi Giá trị đơn đặt hàng không đáp ứng yêu cầu tối thiểu.
missing_buyer_info Lỗi Thiếu thông tin bắt buộc về người mua. Sử dụng trường path để chỉ định trường bị thiếu. Hãy xem ví dụ bên dưới.
address_undeliverable Lỗi Đây là mã lỗi UCP tiêu chuẩn. Sử dụng trường path để cho biết điểm đến cụ thể hoặc mặt hàng bị hạn chế. Hãy xem ví dụ bên dưới.
address_unverifiable Lỗi Không xác minh được địa chỉ bạn cung cấp. Sử dụng trường path để cho biết đó là địa chỉ thực hiện đơn hàng hay địa chỉ thanh toán. Hãy xem ví dụ bên dưới.
missing_fulfillment_info Lỗi Thiếu thông tin bắt buộc về việc thực hiện đơn hàng. Sử dụng trường path để chỉ định trường bị thiếu.
eligibility_invalid Lỗi Người dùng hoặc đơn đặt hàng không đủ điều kiện thực hiện hành động này. Đây là mã lỗi UCP tiêu chuẩn. Sử dụng trường path để biết thông tin cụ thể.
discount_code_invalid Cảnh báo Mã giảm giá không hợp lệ. Không tìm thấy mã hoặc mã không đúng định dạng.
discount_code_expired Cảnh báo Mã giảm giá đã hết hạn.
discount_code_already_applied Cảnh báo Mã giảm giá đã được áp dụng.
discount_code_combination_disallowed Cảnh báo Bạn không thể kết hợp mã giảm giá với các ưu đãi khác.
discount_code_user_not_logged_in Cảnh báo Người dùng phải đăng nhập để sử dụng mã giảm giá.
discount_code_user_ineligible Cảnh báo Người dùng không đủ điều kiện sử dụng mã giảm giá.
missing_billing_info Lỗi Thiếu thông tin thanh toán bắt buộc. Sử dụng trường path để chỉ định các trường địa chỉ thanh toán bị thiếu. Hãy xem ví dụ bên dưới.
identity_required Lỗi Thao tác được yêu cầu cần có danh tính người dùng, nhưng danh tính đó không có, không hợp lệ, đã hết hạn hoặc không xác minh được. Đối với REST, hãy sử dụng mã trạng thái 401. Hãy xem ví dụ bên dưới.
insufficient_scope Lỗi Mã thông báo nhận dạng người dùng hợp lệ nhưng thiếu(các) phạm vi mà thao tác yêu cầu. Đối với REST, hãy sử dụng mã trạng thái 403. Hãy xem ví dụ bên dưới.
payment_declined Lỗi Khoản thanh toán đã bị tổ chức phát hành thẻ hoặc ngân hàng từ chối. Lý do có thể là không đủ tiền, nghi ngờ gian lận hoặc có vấn đề về thẻ. Hãy xem ví dụ bên dưới.
payment_failed Lỗi Khoản thanh toán không thành công do sự cố kỹ thuật trong quá trình xử lý (chẳng hạn như lỗi mạng, hết thời gian chờ của cổng hoặc vấn đề về việc tích hợp) khiến ngân hàng không thể đưa ra quyết định.
payment_ineligible Lỗi Phương thức thanh toán đã chọn không được chấp nhận. Phù hợp với trường hợp người dùng cần thử một phương thức thanh toán khác.
rejected_for_fraud Lỗi Đơn đặt hàng bị từ chối do nghi ngờ có hành vi gian lận. Hãy xem ví dụ bên dưới.

Ví dụ về mã lỗi

Phần này cung cấp các ví dụ về JSON cho mảng messages đối với các mã lỗi cụ thể.

out_of_stock

Thanh toán một mặt hàng:

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

Thanh toán nhiều mặt hàng:

Sử dụng trường path để cho biết chỉ mục của mặt hàng cụ thể đã hết hàng.

{
  "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

Hạn chế ở cấp đơn đặt hàng (ví dụ: không được hỗ trợ mã bưu chính):

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

Quy định hạn chế ở cấp mặt hàng:

Sử dụng trường path để cho biết một mặt hàng cụ thể không thể giao đến vị trí đã chọn (ví dụ: lệnh cấm theo tiểu bang).

{
  "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

Địa chỉ thanh toán:

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

Địa chỉ thực hiện đơn hàng:

{
  "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

Sử dụng trường path để chỉ định các trường còn thiếu trong địa chỉ thanh toán.

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

identity_required

Trong API REST, lỗi này sẽ được trả về với mã trạng thái HTTP 401.

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

insufficient_scope

Trong API REST, lỗi này sẽ được trả về với mã trạng thái 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"
}

Lỗi thanh toán

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."
}