> 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-tw/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-tw/developers/api/authentication)。 |
| `403` | BoxHero 拒絕了此變更，例如違反了庫存規則，或您傳送的 `revision` 已過時 | 查看 `code` 了解原因。重試前請修正請求或取得最新資料。 |
| `404` | 該資源在此團隊中不存在或已被刪除 | 檢查 id。請勿原封不動地重試。 |
| `429` | 請求過多 | 等待後重試。請參閱[速率限制](https://www.boxhero.io/docs/zh-tw/developers/api/rate-limiting)。 |

各端點可能傳回的錯誤類型列於 [API 參考](https://www.boxhero.io/docs/zh-tw/developers/api/reference)中對應的端點下。

## 處理 revision 衝突

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