รหัสข้อผิดพลาด

หน้านี้ระบุรหัสข้อผิดพลาดมาตรฐานที่คุณต้องส่งคืนในการตอบกลับ API เมื่อผสานรวมกับ Google โดยใช้ Universal Commerce Protocol (UCP) รหัสข้อผิดพลาดที่สอดคล้องกันช่วยให้การสื่อสารชัดเจนและช่วยให้ Google จัดการ สถานการณ์ต่างๆ ได้อย่างเหมาะสม

เมื่อเกิดข้อผิดพลาดทางธุรกิจ API ควรแสดงข้อความตอบกลับที่มี code ที่เหมาะสมจากตาราง สำหรับรหัสข้อผิดพลาดบางรายการ เราขอแนะนำให้ใช้ โครงสร้าง JSON ที่เฉพาะเจาะจงสำหรับอาร์เรย์ messages ในการตอบกลับ ตัวอย่างเหล่านี้มีอยู่ในส่วนตัวอย่างรหัสข้อผิดพลาดด้านล่างตาราง ในตัวอย่างเหล่านี้ คุณควรใช้ฟิลด์ path เพื่อระบุข้อมูลที่เฉพาะเจาะจงมากขึ้นเกี่ยวกับตำแหน่งของข้อผิดพลาดภายในออบเจ็กต์คำขอหรือการตอบกลับ

การจัดการข้อผิดพลาด

วิธีรายงานข้อผิดพลาดจะขึ้นอยู่กับประเภทของข้อผิดพลาด ดังนี้

• ข้อผิดพลาดเกี่ยวกับโปรโตคอล/เซิร์ฟเวอร์:

  • ใช้รหัสสถานะ HTTP มาตรฐาน (เช่น 4xx สำหรับข้อผิดพลาดของไคลเอ็นต์, 5xx สำหรับ ข้อผิดพลาดของเซิร์ฟเวอร์) สำหรับปัญหาต่างๆ เช่น คำขอที่มีรูปแบบไม่ถูกต้อง การตรวจสอบสิทธิ์ ไม่สำเร็จ หรือเซิร์ฟเวอร์ไม่พร้อมใช้งาน
  • ดูรายละเอียดได้ในข้อกำหนด UCP

• ข้อผิดพลาด/คำเตือนเกี่ยวกับตรรกะทางธุรกิจ:

  • แสดงสถานะ HTTP 200 OK ซึ่งรวมถึงการปฏิเสธการชำระเงินและการปฏิเสธการประพฤติมิชอบ แม้ว่าเกตเวย์การชำระเงินดาวน์สตรีมจะแสดงข้อผิดพลาด 4xx หรือ 5xx ก็ตาม
  • อธิบายปัญหาภายในอาร์เรย์ messages ในเนื้อหาการตอบกลับ JSON
  • ออบเจ็กต์แต่ละรายการในอาร์เรย์ messages ต้องมีข้อมูลต่อไปนี้
    • type: "error" หรือ "warning"
    • code: รหัสมาตรฐานจากคำแนะนำนี้ อย่าใช้รหัสทั่วไปหรือรหัสที่ไม่รู้จัก เช่น "invalid"
    • content: คำอธิบายที่มนุษย์อ่านได้
    • severity: ต้องระบุเมื่อ type เป็น "error" ฟิลด์นี้จะระบุอย่างชัดเจน ว่าข้อผิดพลาดเป็นข้อผิดพลาดร้ายแรง (unrecoverable) หรือให้คุณแจ้ง ให้ผู้ซื้อแก้ไขปัญหา (recoverable) แทนที่จะอาศัย รหัสข้อผิดพลาดเอง

ประเภทข้อความ: ข้อผิดพลาดเทียบกับคำเตือน

typeฟิลด์ในอาร์เรย์ข้อความจะระบุความรุนแรงของปัญหา UCP กำหนดประเภทหลักๆ ไว้ 2 ประเภท ดังนี้

• error: แสดงว่าดำเนินการที่ขอไม่สำเร็จ แพลตฟอร์มหรือผู้ใช้จะต้องดำเนินการและลองอีกครั้ง ดูข้อกำหนดของข้อผิดพลาดของข้อความ
  • ลักษณะของข้อผิดพลาดที่สิ้นสุดจะกำหนดโดยฟิลด์ severity (unrecoverable หรือ recoverable) ไม่ใช่ข้อผิดพลาด code
• warning: บ่งชี้ว่าระบบไม่ได้บล็อกการดำเนินการ แต่มี สิ่งสำคัญที่ควรแจ้งให้ผู้ใช้ทราบ ซึ่งไม่ได้ หยุดกระบวนการ แต่ให้บริบทที่สำคัญ ดูmessage-warning specification

ข้อมูลอ้างอิงรหัสข้อผิดพลาด

ตัวอย่างรหัสข้อผิดพลาด

ส่วนนี้จะแสดงตัวอย่าง JSON สำหรับอาร์เรย์ messages สำหรับรหัสข้อผิดพลาดที่เฉพาะเจาะจง

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