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:

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

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

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.

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

Để cập nhật hoặc xóa 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.

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