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

# Peringatan & Kode Error Deteksi Liveness

> Semua peringatan modul deteksi liveness Didit — serangan wajah, pemicu kualitas, kecocokan daftar blokir — beserta penyebab dan solusinya.

## Gambaran umum

Peringatan pada laporan liveness menandai setiap kondisi yang diamati Didit saat menjalankan pemeriksaan liveness. Peringatan tersebut masuk ke dalam array `warnings[]` pada setiap item di `liveness_checks[]` (lihat [Laporan liveness](https://docs.didit.me/id/core-technology/liveness/report-liveness.md)), dengan `feature` yang diatur ke `"LIVENESS"`. Setiap entri mengikuti struktur umum [objek peringatan](https://docs.didit.me/id/reference/data-models.md#objek-peringatan): `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

Setiap peringatan memiliki tiga lapisan:

1. **Kode `risk`** — pengidentifikasi stabil yang dapat Anda cocokkan di kode Anda (kode yang tercantum di bawah).
2. **`log_type`** — salah satu dari `information`, `warning`, atau `error`. Risiko penolakan otomatis selalu membawa `error`. Untuk risiko yang dapat dikonfigurasi, nilainya diturunkan dari tindakan yang dikonfigurasi: **Tidak ada tindakan** → `information`, **Tinjauan** → `warning`, **Tolak** → `error`. Untuk risiko berbasis ambang batas (`LOW_LIVENESS_SCORE`, `LOW_FACE_QUALITY`), nilainya adalah `error` saat nilai berada pada atau di bawah ambang batas penolakan dan `warning` saat nilai hanya berada pada atau di bawah ambang batas peninjauan.
3. **Dampak keputusan** — perutean yang sama mendorong `status` laporan liveness: tindakan Tinjauan memindahkannya ke `In Review`, tindakan Tolak (atau risiko penolakan otomatis apa pun) ke `Declined`, dan Tidak ada tindakan membiarkannya tidak berubah.

Beberapa risiko hanya dimunculkan jika metode liveness adalah `PASSIVE` (pemeriksaan beberapa wajah, kualitas, dan luminans). Tabel di bawah mencantumkan kumpulan lengkap kode risiko liveness beserta tingkat keparahannya — tidak ada kode risiko liveness lainnya.

## Kondisi tolak otomatis

Risiko-risiko berikut selalu memaksa laporan liveness (dan sesi) menjadi `Declined`, dengan `log_type: "error"`:

| Risiko | Pemicu |
| - | - |
| `NO_FACE_DETECTED` | Tidak ada wajah yang ditemukan selama pengambilan liveness, atau pengguna telah menghabiskan semua percobaan ulang. |
| `LIVENESS_FACE_ATTACK` | Model mendeteksi serangan presentasi (topeng, pemutaran ulang layar, spoofing sekelas deepfake). |
| `FACE_IN_BLOCKLIST` | Wajah cocok dengan entri pada daftar blokir wajah aplikasi Anda. |
| `AGE_BELOW_MINIMUM` | Usia perkiraan berada di bawah batas minimum yang dikonfigurasi. Hanya dimunculkan pada alur kerja verifikasi usia adaptif dan node `AGE_ESTIMATION`. |
| `AGE_NOT_DETECTED` | Usia tidak dapat diperkirakan. Hanya dimunculkan pada alur estimasi usia dengan fallback verifikasi identitas yang dinonaktifkan. |

Saat `NO_FACE_DETECTED` terpicu, `LOW_LIVENESS_SCORE` diredam (tidak ada wajah yang dapat dinilai).

## Pengaturan verifikasi yang dapat dikonfigurasi

Di konsol Didit, risiko liveness dikelompokkan di bawah pengaturan alur kerja berikut:

| Grup | Risiko | Konfigurasi |
| - | - | - |
| **Ambang batas skor liveness** | `LOW_LIVENESS_SCORE` | Ambang batas peninjauan + ambang batas penolakan pada `score`. Nilai yang berada pada atau di bawah ambang batas peninjauan → `In Review`; nilai yang berada pada atau di bawah ambang batas penolakan → `Declined`. |
| **Tindakan wajah duplikat** | `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` | Satu pengaturan bersama: Tidak ada tindakan (default) / Tinjauan / Tolak. Dilewati sepenuhnya saat wajah yang cocok berada di daftar izin wajah Anda. |
| **Ketidakcocokan identitas wajah duplikat** | `DUPLICATED_FACE_NAME_MISMATCH` | Pengaturan tersendiri (`face_liveness_duplicated_face_name_mismatch_action`): Tidak ada tindakan / Tinjauan (default) / Tolak. Hanya dievaluasi saat `DUPLICATED_FACE` juga terpicu — lihat di bawah. |
| **Pencocokan wajah serangan liveness** | `FACE_MATCHES_LIVENESS_ATTACK` | Pengaturan tersendiri (`face_liveness_attack_face_match_action`): Tidak ada tindakan (default) / Tinjauan. Opsi Tolak yang ditetapkan di sini diterima tetapi diterapkan sebagai Tinjauan. Juga tersedia pada node Estimasi Usia. |
| **Kemungkinan wajah dalam daftar blokir** | `POSSIBLE_FACE_IN_BLOCKLIST` | Tidak dapat dikonfigurasi di alur kerja — selalu diarahkan ke Tinjauan (`log_type: "warning"`). |
| **Tindakan beberapa wajah** *(hanya pasif)* | `MULTIPLE_FACES_DETECTED` | Tidak ada tindakan (default) / Tinjauan / Tolak. |
| **Ambang batas kualitas wajah** *(hanya pasif)* | `LOW_FACE_QUALITY` | Ambang batas peninjauan (default 15) + ambang batas penolakan (default 0, artinya penolakan dinonaktifkan). |
| **Luminans wajah** *(hanya pasif)* | `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE` | Ambang batas min / maks (default 20 / 80 pada skala ternormalisasi 0–100) + tindakan per arah (default Tinjauan). |
| **Ambang batas usia** *(alur kerja adaptif / node `AGE_ESTIMATION`)* | `AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED` | Ambang batas usia minimum dan ambang batas usia borderline; kedua risiko secara otomatis menyebabkan langkah liveness ditolak. Dengan fallback verifikasi identitas yang diaktifkan, alur kerja mengarahkan pengguna ke pemeriksaan dokumen alih-alih mengakhiri sesi. |

## Peringatan yang dihasilkan

### Liveness inti

| Risiko | Penyebab | Tingkat keparahan | Memengaruhi status? | Remediasi |
| - | - | - | - | - |
| `NO_FACE_DETECTED` | Tidak ada wajah yang ditemukan selama pengambilan gambar, atau pengguna telah menghabiskan batas percobaan ulang (`MAX_ATTEMPTS_REACHED`). | `error` | **Penolakan otomatis** | Ambil ulang gambar dengan pencahayaan yang lebih baik; pastikan wajah berada di tengah. |
| `LIVENESS_FACE_ATTACK` | Model mendeteksi serangan presentasi. | `error` | **Penolakan otomatis** | Perlakukan sebagai penipuan. Sesi ditolak secara otomatis. |
| `LOW_LIVENESS_SCORE` | `score` berada pada atau di bawah ambang batas peninjauan alur kerja. Tidak ditampilkan jika `NO_FACE_DETECTED` juga ada. | `warning`; meningkat menjadi `error` ketika skor berada pada atau di bawah ambang batas penolakan | Dapat dikonfigurasi (ambang batas peninjauan / penolakan) | Ambil ulang gambar; sesuaikan ambang batas jika Anda mendapati positif palsu. |

### Integritas saluran pengambilan

Sinyal serangan injeksi yang dilaporkan oleh klien pada saat pengambilan. Berbeda dari serangan presentasi (artefak yang ditempatkan di depan kamera asli), sinyal-sinyal ini menjelaskan umpan kamera itu sendiri yang diganti atau disadap.

Masing-masing dapat dikonfigurasi per alur kerja dan secara default adalah **tanpa tindakan**, sehingga mengaktifkan fitur ini tidak mengubah keputusan apa pun sampai Anda memilihnya.

| Risiko | Penyebab | Kunci konfigurasi | Default |
| - | - | - | - |
| `VIRTUAL_CAMERA_DETECTED` | Perangkat pengambilan diidentifikasi sebagai kamera virtual perangkat lunak (OBS, ManyCam, Snap Camera, DroidCam, dan sejenisnya), bukan kamera fisik. | `virtual_camera_action` | `NO_ACTION` |
| `EXTERNAL_CAPTURE_DEVICE_DETECTED` | Perangkat pengambilan merupakan kamera eksternal atau kartu pengambilan, bukan kamera bawaan. | `external_capture_device_action` | `NO_ACTION` |
| `FRAME_INJECTION_SUSPECTED` | Frame yang diambil menunjukkan indikator penggabungan perangkat lunak atau injeksi ke dalam pipeline kamera, bukan pengambilan langsung yang asli, **atau** pengambilan dilakukan pada perangkat keras yang diemulasikan atau divirtualisasikan (emulator Android, atau mesin virtual desktop), tempat sensor kamera fisik tidak ada dan setiap frame disediakan oleh host. | `frame_injection_action` | `NO_ACTION` |
| `INJECTION_ATTACK_DETECTED` | Pengambilan diinjeksikan dan bukan diambil oleh kamera perangkat itu sendiri: kamera virtual perangkat lunak, umpan kamera yang dihasilkan oleh halaman atau otomatisasi browser, kamera yang di-hook, atau alat instrumentasi yang terpasang pada aplikasi. `additional_data.reasons` hanya mencantumkan alasan yang membuktikannya. Sinyal yang dapat dihasilkan oleh orang asli tidak akan pernah memicunya. Pada liveness dan pencocokan wajah, ini mengikuti `frame_injection_action`, sehingga keputusan swafoto tidak berubah. | `frame_injection_action` | `NO_ACTION` |
| `SCREEN_CAPTURE_DURING_CAPTURE` | Perekaman layar atau berbagi layar sedang aktif di perangkat selama pengambilan biometrik. | `screen_capture_action` | `NO_ACTION` |

> [!NOTE]
>
> Browser tidak mengekspos atestasi sumber kamera tingkat OS ke vendor mana pun, sehingga di web sinyal-sinyal ini berfungsi sebagai bukti penguat dan bukan bukti mutlak. Di web, vonis `null` berarti **tidak ditentukan** (label perangkat tidak tersedia hingga izin kamera diberikan) dan tidak pernah memicu risiko.

Kamera virtual diidentifikasi berdasarkan nama perangkatnya, sehingga kamera yang disajikan sistem operasi dengan nama biasa tidak dikenali dengan cara tersebut. Di dalam emulator Android, kamera yang dipetakan ulang diberi label seperti halnya kamera bawaan, itulah sebabnya kasus perangkat keras yang diemulasikan dilaporkan melalui `FRAME_INJECTION_SUSPECTED`: kasus ini dideteksi dari lingkungan perangkat - tumpukan rendering dan model perangkat yang dilaporkan dalam user agent - bukan dari nama kamera. Temuan yang dipicu dari lingkungan perangkat memuat `additional_data.reason: "emulated_capture_device"`, membedakannya dari analisis frame oleh model liveness itu sendiri.

> [!NOTE]
>
> Mendeteksi mesin dari browser merupakan bukti, bukan atestasi, dan penyerang yang gigih dapat memanipulasinya. SDK mobile native melaporkan sinyal integritas tingkat sistem operasi yang lebih kuat yang tidak dapat dilihat oleh browser (emulator, perangkat yang di-root atau di-jailbreak, pengaitan runtime, debugger yang terpasang), masing-masing dengan tindakannya sendiri yang dapat dikonfigurasi di bawah [Integritas perangkat dan runtime](https://docs.didit.me/id/core-technology/ip-analysis/warnings-ip-analysis.md#integritas-perangkat-dan-runtime). Sinyal-sinyal ini meningkatkan biaya penyerang secara signifikan, tetapi secara mandiri tidak membuktikan bahwa pengambilan berasal dari perangkat asli. Sinyal integritas perangkat independen dari metode liveness, sehingga dapat digabungkan dengan metode Passive, 3D Flash, atau 3D Action & Flash mana pun.

### Forensik kewajaran rekaman

`LIVENESS_VIDEO_ANOMALY` dihitung **di sisi server pada rekaman liveness yang disimpan**, terpisah dari model liveness. Pemeriksaan ini mendeteksi urutan bergerak yang berulang di beberapa siklus, konsisten dengan umpan yang berulang.

| Risiko | Penyebab | Kunci konfigurasi | Default |
| - | - | - | - |
| `LIVENESS_VIDEO_ANOMALY` | Rekaman berisi urutan bergerak yang berulang. Gangguan kamera (stall), frame diam yang berulang, jeda awal yang gelap, dan pengiriman frame yang lambat saja tidak memicu sinyal ini. | `face_liveness_video_anomaly_action` | `NO_ACTION` |

Atur tindakan pada node Liveness atau Estimasi Usia Anda: `NO_ACTION` mencatat temuan informasional, `REVIEW` dapat meningkatkan verifikasi yang sudah diputuskan menjadi Dalam Peninjauan, dan `DECLINE` dapat meningkatkannya menjadi Ditolak. Pemeriksaan ini berjalan secara asinkron, sehingga eskalasi dapat terjadi setelah hasil awal keluar. Keputusan yang sudah ada dan lebih berat tidak akan diturunkan tingkatnya, dan keputusan peninjauan manual tetap dipertahankan.

Temuan versi 2 mencakup `forensics_version: 2`, bukti `repeated_sequence`, dan `repeated_moving_sequence` di dalam `anomaly_reasons`. Metrik pengiriman seperti `unique_frame_ratio`, `static_pair_ratio`, `decoded_fps_ratio`, dan `max_frame_gap_seconds` tetap menjadi diagnostik; metrik tersebut tidak dapat membuktikan adanya pemutaran ulang (replay) secara mandiri. Temuan yang lebih lama menjelaskan versi detektor yang digunakan pada saat itu dan tidak diklasifikasikan ulang secara retroaktif.

> [!NOTE]
>
> Ini adalah sinyal tambahan yang konservatif, bukan deteksi lengkap atas media sintetis atau video yang diinjeksikan. Rekaman tanpa anomali bukan merupakan bukti liveness. Pengambilan gambar yang singkat atau ambigu serta pengambilan tanpa bukti pemutaran ulang yang dapat digunakan tetap tidak ditandai oleh pemeriksaan ini. Rekaman yang hilang atau tidak dapat dibaca tidak menghasilkan temuan dari pemeriksaan ini; pemeriksaan verifikasi lainnya tetap berlaku.

### Pencocokan wajah lintas sesi

| Risiko | Penyebab | Data tambahan | Tingkat keparahan |
| - | - | - | - |
| `FACE_IN_BLOCKLIST` | Wajah cocok dengan wajah di daftar blokir. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `error` — **penolakan otomatis** |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Wajah cocok dengan wajah di daftar blokir pada rentang keyakinan lebih rendah. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `warning` — selalu diarahkan ke Review dalam alur kerja |
| `FACE_IN_ALLOWLIST` | Wajah cocok dengan wajah di daftar izin. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — tindakan duplikat wajah dilewati |
| `POSSIBLE_FACE_IN_ALLOWLIST` | Wajah cocok dengan wajah di daftar izin pada rentang keyakinan lebih rendah. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — kemungkinan tindakan duplikat wajah dilewati |
| `DUPLICATED_FACE` | Wajah cocok dengan wajah yang sudah disetujui dari pengguna lain (sesi `Approved` dengan `vendor_data` berbeda, atau wajah yang diimpor terhadap salah satu pengguna vendor Anda). | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Dapat dikonfigurasi — defaultnya `information` |
| `POSSIBLE_DUPLICATED_FACE` | Wajah cocok dengan wajah lain yang telah disetujui atau diimpor pada rentang keyakinan lebih rendah. | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Dapat dikonfigurasi — defaultnya `information` |
| `DUPLICATED_FACE_NAME_MISMATCH` | Dihasilkan bersama `DUPLICATED_FACE` saat identitas sesi yang cocok tidak sesuai dengan nama yang ditetapkan untuk sesi ini (dokumen identitas, `expected_details`, atau pengguna vendor yang ditautkan), menggunakan penilaian dan ambang batas kecocokan nama yang sama dengan verifikasi identitas. Wajah yang digunakan kembali dengan nama berbeda merupakan sinyal penipuan yang lebih kuat daripada sekadar duplikat biasa, sehingga memiliki tindakan tersendiri yang dapat dikonfigurasi. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `name_match_score` | Dapat dikonfigurasi — defaultnya `warning`. Tidak pernah melonggarkan hasil yang dikonfigurasi untuk `DUPLICATED_FACE`, hanya mengeskalasikannya. |
| `DUPLICATED_FACE_DOCUMENT_MISMATCH` | Dihasilkan bersama `DUPLICATED_FACE` saat dokumen identitas pengguna yang cocok menunjukkan tanggal lahir yang berbeda dari dokumen sesi ini. Orang yang sama yang menunjukkan dokumen berbeda (misalnya paspor setelah kartu identitas) atau dokumen yang diperbarui tidak akan ditandai, dan dua sesi yang memiliki nomor dokumen yang sama dari negara yang sama tidak akan pernah ditandai. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `mismatch_dimensions` | Dapat dikonfigurasi (`face_liveness_duplicated_face_document_mismatch_action`) - defaultnya `Review`. Tidak pernah melonggarkan hasil yang dikonfigurasi untuk `DUPLICATED_FACE`, hanya mengeskalasikannya. |
| `FACE_MATCHES_LIVENESS_ATTACK` | Wajah cocok dengan wajah dari sesi aplikasi ini sebelumnya, milik pengguna lain, yang pengambilan liveness-nya sendiri dinilai sebagai serangan dengan keyakinan tinggi. Bukti untuk peninjauan, bukan bukti pasti adanya serangan. | `liveness_attack_session_id`, `liveness_attack_session_number`, `similarity_percentage`, `liveness_attack_sessions_count` | Dapat dikonfigurasi - defaultnya `information` (Tanpa tindakan) |

Untuk kecocokan terhadap wajah yang diimpor atau wajah dari entri daftar (yang tidak memiliki sesi), nilai `*_session_id`, `*_session_number`, dan `api_service` dalam `additional_data` bernilai `null`.

Wajah milik pengguna yang sama (`vendor_data` yang sama, atau pengguna vendor yang sama jika tersedia) dikecualikan dari **seluruh** pencarian indeks — baik deteksi duplikat maupun skrining daftar blokir. Prioritas kecocokan adalah: kecocokan persis dengan daftar blokir → kecocokan persis dengan daftar izin → kecocokan duplikat persis → kemungkinan kecocokan dengan daftar blokir → kemungkinan kecocokan dengan daftar izin → kemungkinan kecocokan duplikat — hanya satu dari enam kode yang saling eksklusif ini yang muncul per laporan. `DUPLICATED_FACE_NAME_MISMATCH` bukan bagian dari kelompok prioritas tersebut: ini adalah kode tambahan yang dihasilkan **selain** `DUPLICATED_FACE` ketika pemeriksaan identitas juga gagal, tidak pernah menggantikannya. `additional_data.name_match_score` tidak pernah memuat nama yang dibandingkan — hanya id dan skor, sehingga tidak ada PII yang masuk ke dalam payload peringatan.

Nama yang ditulis dalam aksara berbeda pada masing-masing dokumen (misalnya Ibrani di satu dokumen dan Latin di dokumen lainnya) dapat menghasilkan skor di bawah ambang batas meskipun kedua sesi tersebut milik orang yang sama. Dalam satu kasus tersebut, `DUPLICATED_FACE_NAME_MISMATCH` tidak dihasilkan ketika dokumen identitas dari kedua sesi saling menguatkan dalam semua hal berikut:

* Kedua dokumen memuat negara penerbit yang sama.
* Pengenal cocok secara persis di antara kedua dokumen. `document_number` dan `personal_number` dianggap setara atau dapat saling dipertukarkan, karena nomor nasional yang sama dapat berada di salah satu kolom tergantung pada jenis dokumen.
* Jika kedua dokumen memuat tanggal lahir, tanggalnya harus sama.

Jika nama menggunakan aksara yang sama; pengenal atau negara penerbit berbeda atau tidak ada; atau tanggal lahir saling bertentangan, peringatan tetap dihasilkan seperti yang dijelaskan di atas.

### Kualitas liveness pasif (hanya saat `method = "PASSIVE"`)

| Risiko | Penyebab | Tingkat keparahan | Remediasi |
| - | - | - | - |
| `MULTIPLE_FACES_DETECTED` | Lebih dari satu wajah terlihat selama pengambilan. Wajah terbesar selalu digunakan untuk penilaian dan pencocokan. | Dapat dikonfigurasi — defaultnya `information` | Lakukan pengambilan ulang tanpa orang lain. |
| `LOW_FACE_QUALITY` | Kualitas wajah di bawah ambang batas peninjauan (default 15). | `warning`; `error` saat di bawah ambang batas penolakan (default 0 — penolakan dinonaktifkan) | Gunakan fokus yang lebih baik / kurangi oklusi / posisikan wajah di tengah. |
| `LOW_FACE_LUMINANCE` | Luminansi ternormalisasi di bawah ambang batas minimum (default 20). | Dapat dikonfigurasi — defaultnya `warning` (tindakan defaultnya Review) | Pencahayaan lebih baik. |
| `HIGH_FACE_LUMINANCE` | Luminansi ternormalisasi di atas ambang batas maksimum (default 80). | Dapat dikonfigurasi — defaultnya `warning` (tindakan defaultnya Review) | Kurangi pencahayaan; hindari cahaya latar. |

`LOW_FACE_LUMINANCE` dan `HIGH_FACE_LUMINANCE` saling eksklusif — luminansi berada di bawah minimum atau di atas maksimum, tidak pernah keduanya.

### Estimasi usia (alur kerja adaptif dan node `AGE_ESTIMATION`)

| Risiko | Penyebab | Tingkat keparahan | Remediasi |
| - | - | - | - |
| `AGE_BELOW_MINIMUM` | Usia hasil estimasi berada di bawah batas minimum yang dikonfigurasi (atau ambang batas yang mendekati batas minimum saat fallback verifikasi identitas diaktifkan). | `error` | Alur kerja beralih ke verifikasi identitas jika dikonfigurasi. |
| `AGE_NOT_DETECTED` | Usia tidak dapat diestimasi dan fallback verifikasi identitas dinonaktifkan. | `error` | Aktifkan fallback atau lakukan pengambilan ulang. |

## String deskripsi persis

API mengembalikan string `short_description` dan `long_description` persis berikut untuk setiap risiko:

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `NO_FACE_DETECTED` | No Face Detected in liveness | The system couldn't identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues. |
| `LIVENESS_FACE_ATTACK` | Liveness Face Attack | The system detected a potential attempt to bypass the liveness check. |
| `LOW_LIVENESS_SCORE` | Low liveness score | The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. |
| `LIVENESS_VIDEO_ANOMALY` | Liveness video stream anomaly | The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live. |
| `FACE_IN_BLOCKLIST` | Face in blocklist | The system identified a face in the blocklist, which means the face is not allowed to be verified. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Possible face in blocklist | The system identified a possible face in the blocklist, which means the face is not allowed to be verified. |
| `FACE_IN_ALLOWLIST` | Face in allowlist | The face matched the application's face allowlist, so duplicate-face actions were skipped for this signal. |
| `POSSIBLE_FACE_IN_ALLOWLIST` | Possible face in allowlist | The face possibly matched the application's face allowlist, so possible duplicate-face actions were skipped for this signal. |
| `DUPLICATED_FACE` | Duplicated face from other approved session | The system identified a duplicated face from another approved session, requiring further investigation. |
| `POSSIBLE_DUPLICATED_FACE` | Possible duplicated face from other approved session | The system identified a possible duplicate face from another approved session, requiring further investigation. |
| `DUPLICATED_FACE_NAME_MISMATCH` | Duplicated face under a different name | The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud. |
| `FACE_MATCHES_LIVENESS_ATTACK` | Face matches a liveness attack | The face in this liveness capture matches a face from an earlier session of this application whose own capture the liveness engine judged to be an attack with high confidence, in a session of another user. A genuine user can be rejected by mistake, so this is a signal for review, not proof of an attack. |
| `MULTIPLE_FACES_DETECTED` | Multiple faces detected | Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review. |
| `LOW_FACE_QUALITY` | Low face quality | The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts. |
| `LOW_FACE_LUMINANCE` | Low face luminance | The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended. |
| `HIGH_FACE_LUMINANCE` | High face luminance | The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended. |
| `AGE_BELOW_MINIMUM` | Age below minimum | The age of the face is below the minimum age threshold for the application. |
| `AGE_NOT_DETECTED` | Age not detected | The system couldn't identify the age of the face, which is necessary for document verification. |

## API deteksi liveness pasif mandiri

[API Deteksi Liveness](https://docs.didit.me/id/standalone-apis/passive-liveness.md) mandiri menggunakan kembali kode risiko yang sama dengan beberapa perbedaan perilaku:

* `NO_FACE_DETECTED` dan `LOW_LIVENESS_SCORE` saling eksklusif — pemeriksaan skor hanya berjalan jika wajah ditemukan. `LOW_LIVENESS_SCORE` terpicu berdasarkan `face_liveness_score_decline_threshold` permintaan (default 30) dan selalu membawa `log_type: "error"`.
* `POSSIBLE_FACE_IN_BLOCKLIST` diperlakukan sebagai penolakan (`log_type: "error"`), bukan peninjauan.
* `MULTIPLE_FACES_DETECTED` membawa `log_type: "warning"`, sedangkan risiko wajah duplikat tetap bersifat informasional. Hanya peringatan tingkat `error` yang mengubah `status` respons mandiri menjadi `Declined`.
* Entri peringatan mandiri mencakup `feature` tetapi tidak menyertakan `node_id`.

## Contoh

### Penolakan otomatis pada serangan yang terdeteksi

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_FACE_ATTACK",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Liveness Face Attack",
    "long_description": "The system detected a potential attempt to bypass the liveness check.",
    "node_id": "liveness_primary"
  }
]
```

### Peringatan yang dapat dikonfigurasi pada pengambilan pasif

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_QUALITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face quality",
    "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_LUMINANCE",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face luminance",
    "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "MULTIPLE_FACES_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Multiple faces detected",
    "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.",
    "node_id": "liveness_primary"
  }
]
```

### Wajah duplikat dengan payload

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "warning",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  }
]
```

Di sini, tindakan wajah duplikat diatur ke Review, sehingga peringatan memuat `log_type: "warning"` dan status laporan liveness adalah `In Review`. Dengan pengaturan default (No action), peringatan ini akan memuat `log_type: "information"`. `api_service` bernilai `null` karena wajah yang cocok berasal dari sesi alur kerja, bukan panggilan API mandiri.

### Wajah duplikat dengan nama berbeda

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "information",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE_NAME_MISMATCH",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null,
      "name_match_score": 42.5
    },
    "log_type": "warning",
    "short_description": "Duplicated face under a different name",
    "long_description": "The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.",
    "node_id": "liveness_primary"
  }
]
```

`DUPLICATED_FACE` tetap pada tindakan terkonfigurasinya sendiri (di sini, No action — `log_type: "information"`), sementara `DUPLICATED_FACE_NAME_MISMATCH` membawa tindakannya sendiri, dengan default Review (`log_type: "warning"`). Status laporan liveness mengikuti yang paling parah dari keduanya: `In Review` di sini, meskipun pengaturan wajah duplikat standar saja tidak akan menandainya.

### Anomali pada pemeriksaan kewajaran rekaman beserta hasil pengukurannya

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_VIDEO_ANOMALY",
    "additional_data": {
      "forensics_version": 2,
      "duration_seconds": 6.0,
      "repeated_sequence": {
        "period_frames": 6,
        "cycles": 3,
        "matched_pairs": 12
      },
      "anomaly_reasons": ["repeated_moving_sequence"]
    },
    "log_type": "information",
    "short_description": "Liveness video stream anomaly",
    "long_description": "The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.",
    "node_id": "liveness_primary"
  }
]
```

Contoh ini menunjukkan bukti pemutaran ulang (replay) dari rekaman yang berisi tiga salinan dari urutan gerakan. `log_type` bernilai `information` karena tindakan yang dikonfigurasi adalah `NO_ACTION`. Diagnostik pengiriman frame, yang dihilangkan dari contoh ini demi ringkasnya penjelasan, tidak memicu temuan tersebut.

## Jenis peringatan

Setiap risiko diberikan tingkat keparahan berdasarkan konfigurasi aplikasi Anda. Tiga tingkat keparahan tersebut adalah:

## Terkait

* [Laporan liveness](https://docs.didit.me/id/core-technology/liveness/report-liveness.md) — skema laporan lengkap dan status.
* [Peringatan pencocokan wajah](https://docs.didit.me/id/core-technology/face-match/warnings-face-match.md) — peringatan terkait pencocokan wajah 1:1.
* [Webhook](https://docs.didit.me/id/integration/webhooks.md) — `session.status.updated` membawa peringatan segera setelah langkah liveness selesai.
* [Model data — Pemeriksaan liveness](https://docs.didit.me/id/reference/data-models.md#pemeriksaan-liveness) — skema kanonis dengan setiap kolom.
* [Model data — Objek peringatan](https://docs.didit.me/id/reference/data-models.md#objek-peringatan) — bentuk setiap entri dalam `warnings[]`.


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