> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Kode Error API Didit: Status, Body dan Perbaikan

> Semua error API Didit: kode status HTTP, bentuk body respons, kode error stabil, dan kegagalan mana yang aman dicoba ulang. Mencakup 401, 403, 409, 429 dan 5xx.

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](#kesalahan-kunci-api) dan [Kredit tidak cukup](#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](https://docs.didit.me/id/integration/rate-limiting.md) | Ya, setelah menunggu |
| `500` | Error tak terduga di sisi Didit | Coba lagi dengan backoff, dan hubungi dukungan jika terus terjadi | Lihat [Coba lagi](#percobaan-ulang-dan-idempotensi) |
| `502` | Layanan yang diandalkan Didit mengembalikan error | Baca `code` | Lihat [Coba lagi](#percobaan-ulang-dan-idempotensi) |
| `503` | Layanan yang diandalkan Didit sedang tidak tersedia sementara | Baca `code` dan coba lagi | Lihat [Coba lagi](#percobaan-ulang-dan-idempotensi) |

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

```javascript theme={null}
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](https://docs.didit.me/id/getting-started/api-authentication.md) dan [Kunci API](https://docs.didit.me/id/console/api-keys.md) 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](https://docs.didit.me/id/integration/sandbox-testing.md) 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](https://docs.didit.me/id/integration/rate-limiting.md): batas, header, dan isi `429`.
* [Autentikasi API](https://docs.didit.me/id/getting-started/api-authentication.md): cara mengirim kunci Anda.
* [Pengujian sandbox](https://docs.didit.me/id/integration/sandbox-testing.md): mereproduksi hasil tanpa data nyata atau tagihan.
* [Webhook](https://docs.didit.me/id/integration/webhooks.md): pengiriman, percobaan ulang, dan urutan.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.