> 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/vi/developers/api/errors.md).

# Lỗi

> Tìm hiểu cấu trúc phản hồi lỗi mà BoxHero API trả về và cách xử lý lỗi trong mã của bạn.

Khi yêu cầu thất bại, BoxHero API phản hồi bằng mã trạng thái lỗi HTTP và một cấu trúc phản hồi lỗi JSON duy nhất:

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "type": "/errors/not-found",
  "title": "No item with id 12345 found in this team.",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "instance": "/items/12345"
}
```

## Các trường

| Trường | Mô tả |
| --- | --- |
| `id` | ID duy nhất của lỗi: `ex_` theo sau là 32 ký tự thập lục phân viết thường. Hãy cung cấp ID này khi liên hệ bộ phận hỗ trợ. |
| `type` | Mã lỗi ổn định, máy có thể đọc được. Hãy rẽ nhánh trong mã dựa trên trường này, không dựa trên `title`. |
| `title` | Tóm tắt dễ đọc cho con người, bằng tiếng Anh. Nội dung câu chữ có thể thay đổi. |
| `correlationID` | ID của yêu cầu: `rq_` theo sau là 32 ký tự thập lục phân viết thường, giống với header phản hồi `X-Correlation-Id`. Chúng tôi dùng nó để tìm yêu cầu của bạn trong log. |
| `instance` | Tài nguyên bị lỗi, ví dụ `/items/12345`. Đường dẫn không có tiền tố `/v1`. |
| `code` | Lý do chi tiết của lỗi, ví dụ `tx-modify-revision-mismatch`. Không phải lúc nào cũng có. Hãy rẽ nhánh theo `type` trước, sau đó theo `code` để xử lý chi tiết hơn. |
| `errors` | Chi tiết theo từng trường, có trong các phản hồi `/errors/invalid-request` (`400`). Mỗi mục có `path` chỉ ra trường không hợp lệ và `message` dễ đọc cho con người. |

Một số lỗi còn kèm id của tài nguyên liên quan, chẳng hạn `item_id` hoặc `order_id`, dưới dạng các trường bổ sung ở cấp cao nhất.

> **Note**
>
> Bạn có thể gửi header yêu cầu `X-Correlation-Id` của riêng mình để liên kết trace của bạn với trace của chúng tôi. Giá trị tương tự sẽ được trả về trong phản hồi và trong `correlationID`.

## Các mã trạng thái thường gặp

| Trạng thái | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `400` | Yêu cầu không hợp lệ, hoặc chế độ của nhóm không hỗ trợ endpoint này | Sửa yêu cầu — `errors` liệt kê các trường không hợp lệ. Không thử lại khi chưa thay đổi gì. |
| `401` | API token bị thiếu hoặc không hợp lệ | Kiểm tra header `Authorization`. Xem [Xác thực](https://www.boxhero.io/docs/vi/developers/api/authentication). |
| `403` | BoxHero từ chối thay đổi — ví dụ: thay đổi vi phạm quy tắc tồn kho hoặc `revision` bạn gửi đã cũ | Kiểm tra `code` để biết lý do. Sửa yêu cầu, hoặc lấy dữ liệu mới nhất, trước khi thử lại. |
| `404` | Tài nguyên không tồn tại trong nhóm này, hoặc đã bị xóa | Kiểm tra id. Không thử lại khi chưa thay đổi gì. |
| `429` | Quá nhiều yêu cầu | Chờ rồi thử lại. Xem [Giới hạn tần suất](https://www.boxhero.io/docs/vi/developers/api/rate-limiting). |

Các loại lỗi mà mỗi endpoint có thể trả về được liệt kê cùng endpoint đó trong [Tài liệu tham khảo API](https://www.boxhero.io/docs/vi/developers/api/reference).

## Xử lý xung đột phiên bản

Để [cập nhật](https://www.boxhero.io/docs/vi/developers/api/reference/transactions/update-transaction) hoặc [xóa](https://www.boxhero.io/docs/vi/developers/api/reference/transactions/delete-transaction) giao dịch, hãy gửi `revision` mới nhất mà bạn đã thấy. Nếu trong lúc đó có người khác đã thay đổi giao dịch, API sẽ từ chối yêu cầu với `403` và `code` là `tx-modify-revision-mismatch`. Hãy rẽ nhánh theo `code`: lấy lại giao dịch, kiểm tra thay đổi, rồi thử lại với `revision` mới.

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