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

# Error

> Pahami amplop error yang dikembalikan BoxHero API dan cara menangani error di kode Anda.

Jika permintaan gagal, BoxHero API merespons dengan status error HTTP dan satu amplop error 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"
}
```

## Field

| Field | Deskripsi |
| --- | --- |
| `id` | ID unik error: `ex_` diikuti 32 karakter heksadesimal huruf kecil. Sertakan ID ini saat Anda menghubungi tim dukungan. |
| `type` | Kode error yang stabil dan dapat dibaca mesin. Gunakan ini untuk percabangan di kode Anda, bukan `title`. |
| `title` | Ringkasan yang dapat dibaca manusia, dalam bahasa Inggris. Kata-katanya dapat berubah. |
| `correlationID` | ID permintaan: `rq_` diikuti 32 karakter heksadesimal huruf kecil, sama dengan header respons `X-Correlation-Id`. Kami menggunakannya untuk menemukan permintaan Anda di log kami. |
| `instance` | Resource yang gagal, misalnya `/items/12345`. Path ini tidak memiliki prefiks `/v1`. |
| `code` | Alasan rinci error, misalnya `tx-modify-revision-mismatch`. Tidak selalu ada. Lakukan percabangan berdasarkan `type` terlebih dahulu, lalu berdasarkan `code` untuk penanganan yang lebih rinci. |
| `errors` | Detail per field, ada pada respons `/errors/invalid-request` (`400`). Setiap entri memiliki `path` yang menunjukkan field yang tidak valid dan `message` yang dapat dibaca manusia. |

Beberapa error juga menyertakan id resource yang terkait, seperti `item_id` atau `order_id`, sebagai field tambahan di tingkat atas.

> **Note**
>
> Anda dapat mengirim header permintaan `X-Correlation-Id` Anda sendiri untuk menghubungkan trace Anda dengan trace kami. Nilai yang sama dikembalikan di respons dan di `correlationID`.

## Kode status umum

| Status | Arti | Yang perlu dilakukan |
| --- | --- | --- |
| `400` | Permintaan tidak valid, atau mode tim tidak mendukung endpoint ini | Perbaiki permintaan — `errors` mencantumkan field yang tidak valid. Jangan mencoba ulang tanpa perubahan. |
| `401` | Token API tidak ada atau tidak valid | Periksa header `Authorization`. Lihat [Autentikasi](https://www.boxhero.io/docs/id/developers/api/authentication). |
| `403` | BoxHero menolak perubahan — misalnya, perubahan melanggar aturan stok atau `revision` yang Anda kirim sudah usang | Periksa `code` untuk mengetahui alasannya. Perbaiki permintaan, atau ambil data terbaru, sebelum mencoba ulang. |
| `404` | Resource tidak ada di tim ini, atau sudah dihapus | Periksa id-nya. Jangan mencoba ulang tanpa perubahan. |
| `429` | Terlalu banyak permintaan | Tunggu lalu coba lagi. Lihat [Batas permintaan](https://www.boxhero.io/docs/id/developers/api/rate-limiting). |

Tipe error yang dapat dikembalikan setiap endpoint tercantum bersama endpoint tersebut di [Referensi API](https://www.boxhero.io/docs/id/developers/api/reference).

## Menangani konflik revisi

Untuk [memperbarui](https://www.boxhero.io/docs/id/developers/api/reference/transactions/update-transaction) atau [menghapus](https://www.boxhero.io/docs/id/developers/api/reference/transactions/delete-transaction) transaksi, kirim `revision` terbaru yang Anda lihat. Jika orang lain mengubah transaksi tersebut sementara itu, API menolak permintaan dengan `403` dan `code` bernilai `tx-modify-revision-mismatch`. Lakukan percabangan berdasarkan `code`: ambil transaksi lagi, periksa perubahannya, lalu coba ulang dengan `revision` yang baru.

```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.
  }
}
```