> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/th/developers/api/errors.md).

# ข้อผิดพลาด

> ทำความเข้าใจโครงสร้างข้อผิดพลาดที่ BoxHero API ส่งคืน และวิธีจัดการข้อผิดพลาดในโค้ดของคุณ

เมื่อคำขอล้มเหลว BoxHero API จะตอบกลับด้วยสถานะข้อผิดพลาด HTTP และโครงสร้างข้อผิดพลาด (error envelope) แบบ JSON หนึ่งชุด:

```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` เป็นฟิลด์ระดับบนสุดเพิ่มเติม

> **Note**
>
> คุณสามารถส่งเฮดเดอร์คำขอ `X-Correlation-Id` ของคุณเองเพื่อเชื่อมโยง trace ของคุณกับของเรา ค่าเดียวกันจะถูกส่งกลับมาในการตอบกลับและใน `correlationID`

## รหัสสถานะที่พบบ่อย

| สถานะ | ความหมาย | สิ่งที่ควรทำ |
| --- | --- | --- |
| `400` | คำขอไม่ถูกต้อง หรือโหมดของทีมไม่รองรับ endpoint นี้ | แก้ไขคำขอ โดย `errors` จะแสดงฟิลด์ที่ไม่ถูกต้อง อย่าลองใหม่โดยไม่แก้ไข |
| `401` | ไม่มี API โทเค็นหรือโทเค็นไม่ถูกต้อง | ตรวจสอบเฮดเดอร์ `Authorization` ดู [การยืนยันตัวตน](https://www.boxhero.io/docs/th/developers/api/authentication) |
| `403` | BoxHero ปฏิเสธการเปลี่ยนแปลง เช่น ขัดกับกฎของสต็อก หรือ `revision` ที่คุณส่งไม่เป็นปัจจุบัน | ตรวจสอบ `code` เพื่อดูสาเหตุ แก้ไขคำขอหรือดึงข้อมูลล่าสุดก่อนลองใหม่ |
| `404` | ไม่มีทรัพยากรนี้ในทีม หรือถูกลบไปแล้ว | ตรวจสอบ id อย่าลองใหม่โดยไม่แก้ไข |
| `429` | คำขอมากเกินไป | รอแล้วลองใหม่ ดู [การจำกัดอัตราคำขอ](https://www.boxhero.io/docs/th/developers/api/rate-limiting) |

ประเภทข้อผิดพลาดที่แต่ละ endpoint อาจส่งคืนระบุไว้พร้อมกับ endpoint นั้นใน[เอกสารอ้างอิง API](https://www.boxhero.io/docs/th/developers/api/reference)

## การจัดการ revision ที่ขัดแย้งกัน

หากต้องการ[แก้ไข](https://www.boxhero.io/docs/th/developers/api/reference/transactions/update-transaction)หรือ[ลบ](https://www.boxhero.io/docs/th/developers/api/reference/transactions/delete-transaction)ธุรกรรม ให้ส่ง `revision` ล่าสุดที่คุณเห็น หากมีผู้อื่นเปลี่ยนแปลงธุรกรรมในระหว่างนั้น API จะปฏิเสธคำขอด้วย `403` และ `code` เป็น `tx-modify-revision-mismatch` ให้แยกกรณีตาม `code`: ดึงธุรกรรมอีกครั้ง ตรวจสอบการเปลี่ยนแปลง แล้วลองใหม่ด้วย `revision` ใหม่

```js
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.
  }
}
```