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:

{
  "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.

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

Tipe error yang dapat dikembalikan setiap endpoint tercantum bersama endpoint tersebut di Referensi API.

Menangani konflik revisi

Untuk memperbarui atau menghapus 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.

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