ข้อผิดพลาด
ทำความเข้าใจโครงสร้างข้อผิดพลาดที่ BoxHero API ส่งคืน และวิธีจัดการข้อผิดพลาดในโค้ดของคุณ
เมื่อคำขอล้มเหลว BoxHero API จะตอบกลับด้วยสถานะข้อผิดพลาด HTTP และโครงสร้างข้อผิดพลาด (error envelope) แบบ JSON หนึ่งชุด:
{ "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a", "type": "/errors/not-found", "title": "No item with id 12345 found in this team.", "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40", "instance": "/items/12345"}| ฟิลด์ | คำอธิบาย |
|---|---|
id | ID ที่ไม่ซ้ำกันของข้อผิดพลาด: ex_ ตามด้วยอักขระเลขฐานสิบหกตัวพิมพ์เล็ก 32 ตัว แนบค่านี้มาด้วยเมื่อติดต่อฝ่ายสนับสนุน |
type | รหัสข้อผิดพลาดที่คงที่และให้เครื่องอ่านได้ ให้แยกกรณีในโค้ดตามค่านี้ ไม่ใช่ตาม title |
title | สรุปที่มนุษย์อ่านได้ เป็นภาษาอังกฤษ ถ้อยคำอาจเปลี่ยนแปลงได้ |
correlationID | ID ของคำขอ: rq_ ตามด้วยอักขระเลขฐานสิบหกตัวพิมพ์เล็ก 32 ตัว ตรงกับเฮดเดอร์การตอบกลับ X-Correlation-Id เราใช้ค่านี้ค้นหาคำขอของคุณในล็อกของเรา |
instance | ทรัพยากรที่ล้มเหลว เช่น /items/12345 พาธนี้ไม่มี prefix /v1 |
code | เหตุผลย่อยของข้อผิดพลาด เช่น tx-modify-revision-mismatch อาจไม่มีเสมอไป ให้แยกกรณีตาม type ก่อน แล้วจึงใช้ code เพื่อจัดการอย่างละเอียดขึ้น |
errors | รายละเอียดระดับฟิลด์ ซึ่งมีในการตอบกลับ /errors/invalid-request (400) แต่ละรายการมี path ที่ระบุตำแหน่งของฟิลด์ที่ไม่ถูกต้อง และ message ที่มนุษย์อ่านได้ |
ข้อผิดพลาดบางรายการยังมี id ของทรัพยากรที่เกี่ยวข้อง เช่น item_id หรือ order_id เป็นฟิลด์ระดับบนสุดเพิ่มเติม
รหัสสถานะที่พบบ่อย
หัวข้อที่มีชื่อว่า “รหัสสถานะที่พบบ่อย”| สถานะ | ความหมาย | สิ่งที่ควรทำ |
|---|---|---|
400 | คำขอไม่ถูกต้อง หรือโหมดของทีมไม่รองรับ endpoint นี้ | แก้ไขคำขอ โดย errors จะแสดงฟิลด์ที่ไม่ถูกต้อง อย่าลองใหม่โดยไม่แก้ไข |
401 | ไม่มี API โทเค็นหรือโทเค็นไม่ถูกต้อง | ตรวจสอบเฮดเดอร์ Authorization ดู การยืนยันตัวตน |
403 | BoxHero ปฏิเสธการเปลี่ยนแปลง เช่น ขัดกับกฎของสต็อก หรือ revision ที่คุณส่งไม่เป็นปัจจุบัน | ตรวจสอบ code เพื่อดูสาเหตุ แก้ไขคำขอหรือดึงข้อมูลล่าสุดก่อนลองใหม่ |
404 | ไม่มีทรัพยากรนี้ในทีม หรือถูกลบไปแล้ว | ตรวจสอบ id อย่าลองใหม่โดยไม่แก้ไข |
429 | คำขอมากเกินไป | รอแล้วลองใหม่ ดู การจำกัดอัตราคำขอ |
ประเภทข้อผิดพลาดที่แต่ละ endpoint อาจส่งคืนระบุไว้พร้อมกับ endpoint นั้นในเอกสารอ้างอิง API
การจัดการ revision ที่ขัดแย้งกัน
หัวข้อที่มีชื่อว่า “การจัดการ revision ที่ขัดแย้งกัน”หากต้องการแก้ไขหรือลบธุรกรรม ให้ส่ง revision ล่าสุดที่คุณเห็น หากมีผู้อื่นเปลี่ยนแปลงธุรกรรมในระหว่างนั้น API จะปฏิเสธคำขอด้วย 403 และ code เป็น tx-modify-revision-mismatch ให้แยกกรณีตาม code: ดึงธุรกรรมอีกครั้ง ตรวจสอบการเปลี่ยนแปลง แล้วลองใหม่ด้วย revision ใหม่
const res = await fetch(`https://rest.boxhero-app.com/v1/transactions/${id}`, { method: "PUT", headers: { Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ revision, memo: "Recounted" }),});
if (res.status === 403) { const error = await res.json(); if (error.code === "tx-modify-revision-mismatch") { // Fetch the transaction again, check the change, then retry with its new revision. }}