エラー

BoxHero API が返すエラーエンベロープと、コードでエラーを処理する方法を説明します。

リクエストが失敗すると、BoxHero API は HTTP エラーステータスと 1 つの 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_` の後に小文字の 16 進数 32 文字が続きます。サポートへのお問い合わせの際にお知らせください。
`type`	機械で読み取れる、変わらないエラーコードです。コードでは `title` ではなく、この値で分岐してください。
`title`	人が読むための英語の概要です。文言は変更される場合があります。
`correlationID`	リクエストの ID です。`rq_` の後に小文字の 16 進数 32 文字が続き、`X-Correlation-Id` レスポンスヘッダーと同じ値です。BoxHero ではこの ID を使ってログからリクエストを探します。
`instance`	失敗したリソースです（例: `/items/12345`）。パスには `/v1` プレフィックスが付きません。
`code`	エラーの詳細な理由です（例: `tx-modify-revision-mismatch`）。常に含まれるとは限りません。まず `type` で分岐し、より細かく処理する場合は `code` で分岐してください。
`errors`	フィールド単位の詳細で、`/errors/invalid-request`（`400`）のレスポンスに含まれます。各エントリーには、無効なフィールドの位置を示す `path` と、人が読むための `message` があります。

一部のエラーには、item_id や order_id など、関係するリソースの 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.
  }
}