Error

Error menggunakan kode status HTTP dan body RFC 9457 dengan Content-Type: application/problem+json:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/recipients/0/email", "message": "Invalid email address" },
    { "pointer": "/recipients", "message": "Missing recipient for role 'company'." },
    { "pointer": "/recipients/1/role", "message": "Unknown role 'cfo'.", "hint": "Template roles: client, company" }
  ],
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Anggota	Arti
`type`	Pengenal yang stabil: `https://bonafidesign.com/problems/<slug>`. Buat percabangan berdasarkan nilai ini (atau slug-nya), bukan berdasarkan `title` atau `detail`
`title`	Ringkasan singkat jenisnya
`status`	Status HTTP
`detail`	Penjelasan yang dapat dibaca manusia untuk kejadian ini
`errors`	Masalah validasi: `pointer` (JSON Pointer ke body permintaan, atau ke query atau variabel), `message`, opsional `hint`
`requestId`	Juga ada di header `x-request-id`. Sertakan saat menghubungi tim dukungan
`upgradeUrl`	Pada pembatasan paket (`402`, `403 plan-upgrade-required`): tempat menambahkan kartu atau meningkatkan paket

Semua masalah validasi dalam satu permintaan dilaporkan sekaligus, sehingga klien dapat menampilkan masing-masing di samping kolom yang tepat.

Jenis error

Status	Slug	Kapan
400	`bad-request`	Permintaan dengan format salah, seperti body yang bukan JSON valid
401	`unauthorized`	Kredensial tidak ada, formatnya salah, dicabut, atau kedaluwarsa
402	`payment-required`	Workspace Free telah menyelesaikan amplop yang termasuk dalam paketnya untuk periode ini; tambahkan kartu atau tingkatkan paket (mode uji tidak terpengaruh)
403	`forbidden`	Terautentikasi tetapi tidak diizinkan: izin yang kurang, kunci API pada endpoint khusus dasbor, permintaan lintas situs
403	`plan-upgrade-required`	Fitur tidak tersedia di paket workspace
403	`verification-required`	Penanda tangan mengirimkan sebelum memverifikasi kode sekali pakainya
404	`not-found`	Resource tidak ada di organisasi Anda, atau rutenya tidak ada
409	`invalid-state`	Tindakan tidak sesuai dengan status saat ini, misalnya membatalkan amplop yang sudah selesai atau membuat sesi untuk penerima yang sudah menandatangani
409	`not-your-turn`	Penanda tangan mengirimkan sebelum grup perutean sebelumnya selesai
409	`document-mismatch`	Dokumen berubah sejak ditampilkan kepada penanda tangan (`viewedDocumentHash`)
409	`already-signed`	Alamat email tersebut sudah menandatangani tautan yang selalu aktif ini
409	`in-use`	Menghapus template yang dipakai oleh amplop atau tautan penandatanganan
409	`no-draft`	Memublikasikan template yang tidak memiliki draf
409	`idempotency-in-progress`	Permintaan dengan `Idempotency-Key` yang sama masih berjalan
409	`conflict`	Konflik lainnya
410	`gone`	Sesi penandatanganan yang sudah dipakai atau sudah kedaluwarsa
413	`payload-too-large`	Unggahan melebihi batasnya (25 MB untuk file template)
415	`unsupported-media-type`	Unggahan dengan jenis yang tidak didukung
422	`validation-error`	Body, query, atau variabel tidak valid; lihat `errors`
422	`idempotency-key-reused`	`Idempotency-Key` yang sama dipakai dengan permintaan yang berbeda
422	`conversion-failed`	Dokumen Word tidak dapat dikonversi
429	`rate-limited`	Terlalu banyak permintaan; tunggu selama `Retry-After` detik jika header tersebut ada
500	`internal`	Error tak terduga. Aman untuk dicoba ulang dengan `Idempotency-Key` yang sama
501	`not-implemented`	Kapabilitas ada di skema tetapi belum tersedia (mis. kode SMS)
503	`converter-unavailable`, `billing-unavailable`	Sebuah dependensi untuk sementara tidak tersedia; coba lagi nanti

Menangani error

const res = await fetch('https://api.bonafidesign.com/v1/envelopes', { method: 'POST', headers, body });
if (!res.ok) {
  const problem = await res.json(); // application/problem+json
  const slug = problem.type.split('/').pop();
  if (slug === 'validation-error') {
    for (const e of problem.errors) form.setError(e.pointer, e.message);
  } else if (slug === 'payment-required') {
    showUpgrade(problem.upgradeUrl);
  } else {
    throw new Error(`${problem.title} (${problem.requestId})`);
  }
}