错误

了解 BoxHero API 返回的错误信封，以及如何在代码中处理错误。

请求失败时，BoxHero API 会返回 HTTP 错误状态码和一个 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 个小写十六进制字符。联系支持团队时请附上此 ID。
`type`	稳定的、机器可读的错误代码。请在代码中根据此字段而不是 `title` 进行分支处理。
`title`	供人阅读的英文摘要。措辞可能会变化。
`correlationID`	请求的 ID：`rq_` 后跟 32 个小写十六进制字符，与 `X-Correlation-Id` 响应头相同。我们会用它在日志中查找您的请求。
`instance`	失败的资源，例如 `/items/12345`。路径不带 `/v1` 前缀。
`code`	错误的具体原因，例如 `tx-modify-revision-mismatch`。并非总是存在。请先根据 `type` 分支，再根据 `code` 进行更细致的处理。
`errors`	字段级详细信息，出现在 `/errors/invalid-request`（`400`）响应中。每个条目都有一个定位无效字段的 `path` 和一条供人阅读的 `message`。

部分错误还会以额外的顶层字段返回相关资源的 id，例如 item_id 或 order_id。

常见状态码

状态码	含义	处理方法
`400`	请求无效，或团队模式不支持此端点	修正请求——`errors` 中列出了无效字段。不要原样重试。
`401`	API 令牌缺失或无效	检查 `Authorization` 请求头。请参阅身份验证。
`403`	BoxHero 拒绝了此更改，例如违反了库存规则，或您发送的 `revision` 已过期	查看 `code` 了解原因。重试前请修正请求或获取最新数据。
`404`	该资源在此团队中不存在或已被删除	检查 id。不要原样重试。
`429`	请求过多	等待后重试。请参阅速率限制。

各端点可能返回的错误类型列在 API 参考中对应的端点下。

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