錯誤

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