Kode Error API Didit: Status, Body dan Perbaikan

API Didit melaporkan kegagalan dengan kode status HTTP dan, hampir di setiap kasus, body JSON. Halaman ini mencantumkan arti setiap status, bentuk body-nya, nilai code yang dapat Anda jadikan dasar percabangan, serta kegagalan mana yang aman untuk dicoba ulang. Andalkan status terlebih dahulu dan code jika tersedia, karena teks pesan dapat berubah.

Kode status

Status	Arti	Yang perlu dilakukan	Coba lagi?
`400`	Permintaan tidak valid: sebuah kolom gagal validasi, atau gambar atau dokumen tidak dapat dibaca	Perbaiki bagian yang disebutkan di body	Setelah memperbaikinya
`401`	Kunci yang Anda kirim salah, tidak valid, dicabut, atau kedaluwarsa	Periksa `DIDIT_API_KEY`, atau buat kunci baru	Setelah memperbaikinya
`402`	Pemeriksaan tidak dapat dibayar, sehingga tidak dijalankan	Isi saldo Anda	Setelah mengisi saldo
`403`	Tidak ada kunci yang dikirim, kunci tidak memiliki akses ke resource atau tindakan ini, permintaan berasal dari luar daftar IP kunci, atau saldo tidak cukup untuk memproses panggilan	Baca body, lalu lihat Kesalahan kunci API dan Kredit tidak cukup	Setelah memperbaikinya
`404`	Resource tidak ada, atau sesi berada di luar alur kerja atau status yang diizinkan untuk kunci	Periksa id dan batasan kunci Anda	Tidak
`409`	Permintaan bertentangan dengan kondisi saat ini, misalnya `Idempotency-Key` yang digunakan ulang atau langkah yang sudah dijalankan	Baca `code` dan muat ulang kondisinya	Bergantung pada `code`
`410`	Resource sudah kedaluwarsa, misalnya sesi atau undangan	Buat yang baru	Tidak
`415`	Body permintaan bukan JSON	Kirim `Content-Type: application/json`	Setelah memperbaikinya
`422`	Alamat dompet cocok dengan lebih dari satu blockchain, sehingga tidak ada yang diskrining atau ditagih	Kirim ulang dengan `blockchain` diisi salah satu dari `candidate_chains`	Setelah memperbaikinya
`429`	Batas laju atau kuota telah tercapai	Tunggu sesuai `Retry-After`; lihat Pembatasan laju	Ya, setelah menunggu
`500`	Error tak terduga di sisi Didit	Coba lagi dengan backoff, dan hubungi dukungan jika terus terjadi	Lihat Coba lagi
`502`	Layanan yang diandalkan Didit mengembalikan error	Baca `code`	Lihat Coba lagi
`503`	Layanan yang diandalkan Didit sedang tidak tersedia sementara	Baca `code` dan coba lagi	Lihat Coba lagi

Body error

Body error tidak memakai format yang sama, jadi bacalah dengan hati-hati. Bentuknya bergantung pada keluarga endpoint:

Bentuk	Tempat muncul	Contoh
`detail`	Sebagian besar error, termasuk kesalahan autentikasi, resource yang tidak ditemukan, dan batas laju	`{"detail": "You do not have permission to perform this action."}`
`detail` dan `code`	Error dengan kode yang stabil	`{"detail": "This application was deleted.", "code": "application_deleted"}`
Error kolom	Validasi input	`{"workflow_id": ["This field is required."]}`
`non_field_errors`	Validasi lintas kolom	`{"non_field_errors": ["..."]}`
Array JSON	Sebagian error validasi, seperti panggilan simulate	`["Scenario can only be armed before the verification starts."]`
`error`	Sebagian besar API mandiri	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`error` dan `code`	Error gambar pada API mandiri	`{"error": "...", "code": "invalid_image"}`
`error` sebagai kode, dengan `detail`	Verifikasi dompet ID digital	`{"error": "insufficient_credits", "detail": "..."}`

Sebuah 500 mungkin tidak memiliki body JSON sama sekali, jadi tangani body yang tidak bisa di-parse.

const raw = await response.text();
let body = {};
try {
  body = JSON.parse(raw);
} catch {
  // A 5xx response may not be JSON: rely on response.status.
}
const code = body.code ?? null;
const message = body.detail ?? body.error ?? (Array.isArray(body) ? body[0] : raw);

Kesalahan kunci API

Yang Anda kirim	Status	`detail`
Tidak ada header `x-api-key`	`403`	`You do not have permission to perform this action.`
Kunci yang salah, tidak valid, atau dicabut	`401`	`Authentication credentials were not provided or are invalid.`
Kunci yang sudah kedaluwarsa	`401`	`This API key has expired.`
Kunci yang digunakan dari luar daftar IP-nya	`403`	`This API key can't be used from this IP address.`
Kunci dengan cakupan terbatas tanpa akses ke resource atau tindakan ini	`403`	`This API key has no access to this endpoint.`
Kunci yang dibatasi pada beberapa alur kerja atau status, pada endpoint yang tidak dapat digunakannya	`403`	`This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`
Kunci yang dibatasi pada beberapa alur kerja atau status, pada sesi di luar batas tersebut	`404`	`Session not found.`
Kunci dari aplikasi yang baru saja dihapus	`403`	`This application was deleted.`, dengan `"code": "application_deleted"`

Selama beberapa menit setelah aplikasi dihapus, API tetap menjawab dengan application_deleted, dan setelah itu API menolak kunci tersebut seperti kunci yang salah lainnya. Jangan coba lagi: aplikasi dan kuncinya sudah tidak ada. Lihat Autentikasi API dan Kunci API untuk cara kerja kunci dan batasannya.

Kredit tidak cukup

Setiap keluarga API melaporkan saldo rendah dengan caranya sendiri:

Panggilan	Status	Body
`POST /v3/session/`	`400`	`{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
Sebagian besar API mandiri	`403`	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`POST /v3/bank/account-check/`	`402`	`{"detail": "...", "code": "insufficient_credits"}`
Verifikasi dompet ID digital	`403`	`{"error": "insufficient_credits", "detail": "..."}`
Transaksi, Travel Rule dan validasi alamat	`403`	`{"detail": "...", "code": "insufficient_credits"}`

Untuk kontrak, pembuatan sesi menghasilkan respons 403 dengan "code": "contract_billing_suspended" selama layanan berbayar ditangguhkan untuk organisasi Anda. Aplikasi sandbox tidak pernah ditagih, sehingga tidak melalui pemeriksaan ini.

Kode error

Kode code ini stabil, sehingga Anda dapat menggunakannya untuk percabangan logika. Sebagian besar muncul di samping detail. Pada verifikasi dompet Digital ID, kodenya adalah nilai dari error.

Akses dan penagihan

Kode	Status	Arti
`insufficient_credits`	`402`, `403`	Saldo tidak cukup untuk membiayai panggilan ini
`contract_billing_suspended`	`403`	Layanan berbayar dijeda untuk organisasi ini
`contract_rate_missing`	`402`, `403`	Kontrak tidak memiliki tarif untuk pemeriksaan ini
`application_deleted`	`403`	Aplikasi milik kunci ini telah dihapus
`organization_deleted`	`403`	Organisasi milik kunci ini telah dihapus
`event_monitoring_disabled`	`403`	Ingesti event belum diaktifkan untuk aplikasi ini
`networks_not_entitled`	`403`	Jaringan penipuan belum diaktifkan untuk organisasi ini

Permintaan dan idempotensi

Kode	Status	Arti
`invalid_image`	`400`	Gambar tidak dapat digunakan
`return_url_invalid`	`400`	URL pengembalian tidak diizinkan
`idempotency_key_invalid`	`400`	`Idempotency-Key` lebih dari 255 karakter
`idempotency_key_reused`	`409`	Kunci ini sudah digunakan dengan badan permintaan yang berbeda
`idempotency_key_in_progress`	`409`	Permintaan pertama dengan kunci ini masih berjalan; tunggu `Retry-After`
`verification_in_progress`	`409`	Pengguna sedang menyelesaikan verifikasi ini sehingga tidak dapat dibatalkan; tunggu `Retry-After`
`feature_override_not_pending`	`409`	Override sudah diterapkan atau dibatalkan

Pemeriksaan bank, telepon, dan risiko

Kode	Status	Arti
`invalid_account_input`	`400`	Detail rekening tidak valid
`country_not_covered`	`404`	Pemeriksaan ini tidak mencakup negara ini atau jenis rekening ini
`bank_not_covered`	`404`	Pemeriksaan ini tidak menjangkau bank ini
`bank_verification_not_available`	`404`	Verifikasi Bank tidak tersedia
`account_check_unavailable`	`503`	Pemeriksaan sedang tidak tersedia dan permintaan tidak dikenai biaya
`phone_provider_unavailable`	`502`	Verifikasi telepon sedang tidak tersedia; tidak ada biaya dan tidak ada percobaan yang terpakai
`risk_lookup_unavailable`	`502`	Pencarian risiko sedang tidak tersedia dan permintaan tidak dikenai biaya

Verifikasi Bisnis (KYB)

Kode	Status	Arti
`kyb_registry_provider_unavailable`	`502`	Registri perusahaan sedang tidak tersedia
`kyb_registry_country_unsupported`	`400`	Pencarian registri tidak mencakup negara ini
`kyb_registry_search_limit_reached`	`429`	Aplikasi telah mencapai batas 600 pencarian berbayar per jam
`kyb_session_not_writable`	`409`	Sesi sudah selesai
`kyb_step_mismatch`	`409`	Sesi berada pada langkah lain; `next_step` menyebutkan langkahnya
`kyb_no_party_drafts`	`409`	Tidak ada draf pihak untuk dikirim
`kyb_parties_already_submitted`	`409`	Pihak-pihak sudah dikirim
`kyb_party_kyc_session_not_deleted`	`409`	Verifikasi pihak masih aktif sehingga tidak dapat dibuat ulang

Dompet Digital ID

Kode	Status	Arti
`wallet_unavailable`	`403`	Dompet ini tidak tersedia untuk aplikasi Anda
`wallet_provider_unavailable`	`502`	Dompet tidak dapat dimulai dan tidak ada yang dibuat
`wallet_not_configured`	`503`	Lingkungan ini tidak dapat menjangkau dompet

Laporan dan kasus

Kode	Status	Arti
`report_deletion_pending`	`409`	Laporan sedang dihapus; ulangi penghapusan untuk menyelesaikan penghapusan file-filenya
`report_storage_unavailable`	`503`	File laporan tidak dapat dihapus permanen; ulangi penghapusan
`wallet_address_deletion_incomplete`	`503`	Sebuah file tersimpan tidak dapat dihapus sehingga penghapusan berhenti; coba lagi
`case_request_not_waiting`	`409`	Permintaan tidak lagi menunggu pelanggan sehingga tidak ada pengingat yang dapat dikirim
`case_request_reminder_too_soon`	`429`	Pengingat baru saja dikirim; `retry_at` menunjukkan kapan Anda dapat mengirim pengingat berikutnya

Tanda Tangan Elektronik

Kode	Status	Arti
`signature_not_found`	`404`	Tanda tangan tidak ada
`signature_field_not_found`	`404`	Kolom tanda tangan tidak ada
`signature_not_signed`	`404`, `409`	Dokumen belum ditandatangani

Saat membuat sesi, masalah dokumen di bawah ini muncul sebagai nilai dari kolom yang bermasalah dengan status 400, misalnya {"sign": "signature_document_changed"}:

Nilai	Arti
`signature_document_changed`	Dokumen berbeda dari dokumen yang dikirim pertama kali
`signature_document_not_supported`	Format dokumen tidak didukung
`signature_document_conversion_failed`	Dokumen tidak dapat dikonversi
`field_anchor_not_found`	Jangkar teks kolom tidak ditemukan dalam dokumen
`field_value_missing`	Sebuah kolom tidak memiliki nilai

Webhook

Kode	Status	Arti
`webhook_url_missing`	`400`	Pengiriman tidak memiliki URL yang tercatat, sehingga tidak ada yang dikirim
`invalid_webhook_payload`	`400`	Data webhook tidak dalam format yang valid
`webhook_resend_error`	`400`	Pengiriman yang tersimpan tidak dapat ditandatangani ulang, atau percobaan tidak dapat diselesaikan

Percobaan ulang dan idempotensi

Sebagian kegagalan aman untuk diulang dan sebagian tidak:

429: tunggu header Retry-After, lalu coba lagi.
502 dan 503: coba lagi dengan penundaan bertahap jika referensi endpoint menyatakan tidak ada tagihan, seperti yang berlaku untuk pemeriksaan telepon, email, bank, dan risiko.
502 pada POST /v3/database-validation/: baca setiap entri validation_errors terlebih dahulu, karena status ini saja tidak berarti kegagalan sementara.
503 pada penghapusan: ulangi permintaan yang sama hingga mengembalikan 200.
4xx lainnya: perbaiki permintaan terlebih dahulu, karena permintaan yang sama akan gagal dengan cara yang sama.

POST /v3/aml/ dan verifikasi dompet Digital ID menerima header Idempotency-Key hingga 255 karakter. Mengulangi permintaan dengan kunci dan isi yang sama akan mengembalikan respons yang tersimpan, sehingga proses dan penagihan hanya dilakukan sekali. Kunci yang sama dengan isi yang berbeda akan mengembalikan 409, dan selama permintaan pertama masih berjalan, endpoint dompet akan mengembalikan 409 dengan Retry-After. POST /v3/session/ tidak memiliki kunci idempotensi, sehingga jika waktu pembuatannya habis, tampilkan daftar sesi Anda berdasarkan vendor_data sebelum membuat sesi lain.

Terkait

Batas laju: batas, header, dan isi 429.
Autentikasi API: cara mengirim kunci Anda.
Pengujian sandbox: mereproduksi hasil tanpa data nyata atau tagihan.
Webhook: pengiriman, percobaan ulang, dan urutan.

Panduan

Autentikasi

Model Context Protocol (MCP)

SDK Web

SDK Native

SDK Server

Integrasi

Kode Error API Didit: Status, Body dan Perbaikan

Kode status

Body error

Kesalahan kunci API

Kredit tidak cukup

Kode error

Akses dan penagihan

Permintaan dan idempotensi

Pemeriksaan bank, telepon, dan risiko

Verifikasi Bisnis (KYB)

Dompet Digital ID

Laporan dan kasus

Tanda Tangan Elektronik

Webhook

Percobaan ulang dan idempotensi

Terkait

​Kode status

​Body error

​Kesalahan kunci API

​Kredit tidak cukup

​Kode error

​Akses dan penagihan

​Permintaan dan idempotensi

​Pemeriksaan bank, telepon, dan risiko

​Verifikasi Bisnis (KYB)

​Dompet Digital ID

​Laporan dan kasus

​Tanda Tangan Elektronik

​Webhook

​Percobaan ulang dan idempotensi

​Terkait

Kode status

Body error

Kesalahan kunci API

Kredit tidak cukup

Kode error

Akses dan penagihan

Permintaan dan idempotensi

Pemeriksaan bank, telepon, dan risiko

Verifikasi Bisnis (KYB)

Dompet Digital ID

Laporan dan kasus

Tanda Tangan Elektronik

Webhook

Percobaan ulang dan idempotensi

Terkait