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

# 错误

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

请求失败时，BoxHero API 会返回 HTTP 错误状态码和一个 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 个小写十六进制字符。联系支持团队时请附上此 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`。

> **Note**
>
> 您可以发送自己的 `X-Correlation-Id` 请求头，将您的追踪与我们的追踪关联起来。相同的值会在响应和 `correlationID` 中返回。

## 常见状态码

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

各端点可能返回的错误类型列在 [API 参考](https://www.boxhero.io/docs/zh-cn/developers/api/reference)中对应的端点下。

## 处理 revision 冲突

要[更新](https://www.boxhero.io/docs/zh-cn/developers/api/reference/transactions/update-transaction)或[删除](https://www.boxhero.io/docs/zh-cn/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.
  }
}
```