Kode error
Halaman ini adalah sumber kebenaran tunggal untuk penanganan error. Kode error khusus SDK didokumentasikan di halaman Error handling masing-masing SDK; halaman ini mencakup error di tingkat kontrak API.
Kode status HTTP
| Kode | Arti | Berlaku di mana |
|---|---|---|
200 OK | Permintaan berhasil. | Semua kontrak. |
201 Created | Resource dibuat (jarang; sebagian besar pembuatan mengembalikan 200). | Kontrak API. |
400 Bad Request | Payload tidak valid atau field yang diperlukan tidak ada. Body mengidentifikasi field yang bermasalah. | Semua kontrak. |
401 Unauthorized | Autentikasi tidak ada, kedaluwarsa, atau tidak valid. | Semua kontrak. |
403 Forbidden | Autentikasi valid tetapi tenant tidak diaktifkan untuk resource yang diminta (misalnya, memanggil kemampuan yang tidak ada dalam APIKEY Anda). | Web & SDK, API. |
404 Not Found | Resource tidak ada atau tidak milik tenant yang terautentikasi. | Semua kontrak. |
409 Conflict | Resource ada tetapi tidak dalam status yang tepat untuk operasi ini (misalnya, mengambil dokumen dari proses yang masih berlangsung). | Web & SDK, API. |
410 Gone | Resource pernah ada tetapi dihapus sesuai kebijakan retensi (endpoint pengambilan dokumen), atau proses ada tetapi berakhir dalam kondisi error — lihat Dapatkan Proses. | Endpoint pengambilan dokumen; API Dapatkan Proses. |
429 Too Many Requests | Anda mencapai rate limit. Coba ulang dengan exponential backoff. | Semua kontrak. |
5xx | Error platform. Coba ulang dengan backoff; jika persisten, hubungi dukungan dengan response body dan timestamp. | Semua kontrak. |
Error autentikasi (401)
| Penyebab | Gejala |
|---|---|
| Private key salah (assertion ditandatangani dengan key yang salah) | 401, Authentication failed (1.2.21) |
aud tidak sesuai dengan URL environment | 401 |
Klaim exp sudah lewat | 401, Authentication failed |
Algoritma tidak didukung (gunakan RS256) | 401 |
| Campuran kredensial sandbox / production | 401, meskipun kredensial terlihat benar |
Header APIKEY tidak ada (hanya kontrak API) | 401 |
x-api-key tidak valid (hanya Magic Link) | 401 |
Lihat Authentication > Common errors untuk daftar pemecahan masalah lengkap.
Hasil tingkat kemampuan (200 dengan hasil negatif)
200 OK tidak berarti pengguna lulus verifikasi — artinya platform menyelesaikan pekerjaan. Keputusan yang menghadap pengguna berada di response body, bukan status HTTP:
| Field | Nilai negatif | Muncul di mana |
|---|---|---|
process.result | PROCESS_RESULT_FAILED | Web & SDK |
process.authenticationInfo.livenessResult | NO | Web & SDK |
liveness | 2 | API |
unicoId.result | no | API |
data.result.status | not_verified | Magic Link |
Kebijakan retry
| Status | Harus dicoba ulang? | Cara |
|---|---|---|
5xx | Ya | Exponential backoff (1s, 2s, 4s, 8s, …). Batasi hingga 5 percobaan. |
429 | Ya | Patuhi header Retry-After jika ada; jika tidak, gunakan exponential backoff. |
4xx (lainnya) | Tidak | Permintaan salah. Perbaiki input sebelum mencoba ulang. |
401 | Kondisional | Refresh access token sekali. Jika permintaan baru juga mengembalikan 401, masalahnya struktural — jangan coba ulang. |
Platform IDCloud saat ini tidak mengekspos mekanisme idempotency-key pada endpoint pembuatan. Berhati-hatilah saat mencoba ulang POST /client/v1/process atau POST /processes/v1 — error jaringan pada 5xx mungkin sudah berhasil di sisi server, dan percobaan ulang akan membuat proses duplikat. Jika ragu, ambil proses terbaru berdasarkan ID korelasi internal Anda sebelum mencoba ulang.
Di mana error SDK berada
Katalog error Web SDK, Android SDK, iOS SDK, dan Flutter SDK didokumentasikan di halaman Error handling khusus masing-masing SDK:
- Web SDK > Error handling
- Android SDK > Error handling
- iOS SDK > Error handling
- Flutter SDK > Error handling
Ini mencakup error di sisi perangkat (izin kamera ditolak, timeout pengambilan, jaringan tidak dapat dijangkau di perangkat) — terpisah dari error di sisi API yang didokumentasikan di sini.