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

# エラー

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

リクエストが失敗すると、BoxHero API は HTTP エラーステータスと 1 つの 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_` の後に小文字の 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 が追加のトップレベルフィールドとして含まれます。

> **Note**
>
> 独自の `X-Correlation-Id` リクエストヘッダーを送信すると、自社のトレースと BoxHero のトレースを結び付けられます。同じ値がレスポンスと `correlationID` で返されます。

## 主なステータスコード

| ステータス | 意味 | 対処方法 |
| --- | --- | --- |
| `400` | リクエストが無効か、チームのモードがこのエンドポイントに対応していません | リクエストを修正してください。`errors` に無効なフィールドが記載されています。変更せずに再試行しないでください。 |
| `401` | API トークンが送信されていないか、無効です | `Authorization` ヘッダーを確認してください。[認証](https://www.boxhero.io/docs/ja/developers/api/authentication)をご覧ください。 |
| `403` | BoxHero が変更を拒否しました。たとえば、在庫のルールに違反しているか、送信した `revision` が最新ではありません | `code` で理由を確認してください。再試行する前に、リクエストを修正するか最新のデータを取得してください。 |
| `404` | リソースがこのチームに存在しないか、削除されています | id を確認してください。変更せずに再試行しないでください。 |
| `429` | リクエストが多すぎます | 待機してから再試行してください。[レート制限](https://www.boxhero.io/docs/ja/developers/api/rate-limiting)をご覧ください。 |

各エンドポイントが返す可能性のあるエラータイプは、[API リファレンス](https://www.boxhero.io/docs/ja/developers/api/reference)の各エンドポイントに記載されています。

## revision の競合を処理する

履歴を[更新](https://www.boxhero.io/docs/ja/developers/api/reference/transactions/update-transaction)または[削除](https://www.boxhero.io/docs/ja/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.
  }
}
```