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

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

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

รหัสข้อผิดพลาด ประเภทที่แนะนำ คำอธิบาย
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 ข้อผิดพลาด คำสั่งซื้อถูกปฏิเสธเนื่องจากสงสัยว่ามีการฉ้อโกง ดูตัวอย่างด้านล่าง

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

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

out_of_stock

การชำระเงินสินค้า 1 รายการ

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