ข้ามไปยังเนื้อหา

ข้อผิดพลาด

ทำความเข้าใจโครงสร้างข้อผิดพลาดที่ 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"
}
ฟิลด์คำอธิบาย
idID ที่ไม่ซ้ำกันของข้อผิดพลาด: ex_ ตามด้วยอักขระเลขฐานสิบหกตัวพิมพ์เล็ก 32 ตัว แนบค่านี้มาด้วยเมื่อติดต่อฝ่ายสนับสนุน
typeรหัสข้อผิดพลาดที่คงที่และให้เครื่องอ่านได้ ให้แยกกรณีในโค้ดตามค่านี้ ไม่ใช่ตาม title
titleสรุปที่มนุษย์อ่านได้ เป็นภาษาอังกฤษ ถ้อยคำอาจเปลี่ยนแปลงได้
correlationIDID ของคำขอ: 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 ดู การยืนยันตัวตน
403BoxHero ปฏิเสธการเปลี่ยนแปลง เช่น ขัดกับกฎของสต็อก หรือ revision ที่คุณส่งไม่เป็นปัจจุบันตรวจสอบ code เพื่อดูสาเหตุ แก้ไขคำขอหรือดึงข้อมูลล่าสุดก่อนลองใหม่
404ไม่มีทรัพยากรนี้ในทีม หรือถูกลบไปแล้วตรวจสอบ id อย่าลองใหม่โดยไม่แก้ไข
429คำขอมากเกินไปรอแล้วลองใหม่ ดู การจำกัดอัตราคำขอ

ประเภทข้อผิดพลาดที่แต่ละ endpoint อาจส่งคืนระบุไว้พร้อมกับ endpoint นั้นในเอกสารอ้างอิง API

หากต้องการแก้ไขหรือลบธุรกรรม ให้ส่ง 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.
}
}