Peringatan Pencocokan Wajah & Kode Error

Gambaran umum

Peringatan pada laporan pencocokan wajah menandai setiap kondisi yang diamati Didit saat menjalankan perbandingan wajah 1:1. Peringatan tersebut masuk ke dalam array warnings[] pada setiap item di face_matches[] (lihat Laporan pencocokan wajah). Setiap entri juga memuat feature: "FACEMATCH" dan node_id dari node alur kerja yang memunculkannya. Setiap peringatan memiliki tiga lapisan:

Kode risk — pengidentifikasi stabil yang dapat Anda cocokkan di kode Anda.
log_type — information, warning, atau error, yang diperoleh dari ambang batas skor kemiripan alur kerja Anda.
Dampak keputusan — ditetapkan oleh ambang batas peninjauan dan penolakan alur kerja untuk skor kemiripan.

Modul pencocokan wajah sengaja dibuat ringkas — hanya ada lima kode risiko, yang tercantum lengkap di bawah ini.

Kondisi penolakan otomatis

Risiko berikut selalu memaksa laporan pencocokan wajah (dan sesi) menjadi Declined:

Risiko	Pemicu
`NO_REFERENCE_IMAGE`	Salah satu dari `source_image` (referensi) atau `target_image` (swafoto) tidak ada, sehingga perbandingan tidak dapat dilakukan.

Saat NO_REFERENCE_IMAGE dipicu, LOW_FACE_MATCH_SIMILARITY disembunyikan (karena tidak ada yang dapat dinilai). Terdapat satu pengecualian. Saat langkah ID diselesaikan melalui pencarian non-dokumen yang registrinya tidak mengembalikan potret dan tidak memeriksa wajah, Pencocokan Wajah secara bawaan tidak memiliki apa pun untuk dibandingkan dengan hasil tangkapan langsung. Hal tersebut dilaporkan sebagai FACE_MATCH_NOT_COMPUTED dengan skor null dan diputuskan oleh face_match_not_computed_action (di bawah), bukan sebagai penolakan otomatis.

Pengaturan verifikasi yang dapat dikonfigurasi

Di konsol Didit, skor kemiripan pencocokan wajah diatur oleh dua ambang batas (tanpa tombol alih Setujui/Tinjau/Tolak):

Pengaturan	Default	Perilaku
`face_match_score_review_threshold`	70	Saat `score` ≤ nilai ini, `LOW_FACE_MATCH_SIMILARITY` dipicu dan status berubah menjadi `In Review`.
`face_match_score_decline_threshold`	50	Saat `score` ≤ nilai ini, peringatan yang sama meningkat menjadi `error` dan status berubah menjadi `Declined`.

Tingkatkan ambang batas peninjauan jika Anda mengamati terlalu banyak persetujuan palsu; turunkan ambang batas penolakan jika Anda mengamati terlalu banyak penolakan palsu. Pengaturan terpisah mengontrol apa yang terjadi jika skor kemiripan tidak dapat dihitung sama sekali: tidak ada wajah yang terdeteksi di salah satu gambar, atau pencarian non-dokumen tidak menyisakan referensi apa pun untuk dibandingkan:

Pengaturan	Default	Perilaku
`face_match_not_computed_action`	`REVIEW`	Tindakan yang diterapkan setelah hasil “tidak dapat dihitung” berstatus terminal. `REVIEW` mengirim laporan ke `In Review`; `DECLINE` menetapkannya menjadi `Declined`. (Tidak ada opsi persetujuan otomatis — skor yang tidak pernah dihitung tidak akan pernah diloloskan secara diam-diam.)

Tindakan ini mengatur FACE_MATCH_NOT_COMPUTED (tidak ada wajah pada potret dokumen, atau tidak ada referensi sama sekali setelah pencarian non-dokumen) dan NO_FACE_IN_SELFIE setelah batas percobaan habis (tidak ada wajah pada swafoto setelah percobaan ulang pengguna). Jika masalahnya adalah swafoto, pengguna terlebih dahulu diminta untuk mengambil ulang — lihat di bawah — dan tindakan ini hanya berlaku jika wajah tetap tidak dapat terdeteksi setelah batas percobaan habis. Kegagalan akibat kemiripan rendah juga memasuki loop percobaan ulang pengambilan sebelum statusnya ditetapkan secara permanen: pengguna mendapatkan total hingga face_match_max_attempts percobaan (default 3, dapat dikonfigurasi 2–5 per node alur kerja) untuk mengambil ulang. Kegagalan NO_FACE_IN_SELFIE menggunakan loop percobaan ulang yang sama, karena mengambil ulang swafoto yang lebih jelas dapat memperbaikinya. Kegagalan FACE_MATCH_NOT_COMPUTED tidak melakukan percobaan ulang — potret dokumen tidak dapat diambil ulang pada langkah ini. Hanya setelah batas percobaan habis, status percobaan terakhir akan diterapkan — dan FACE_MATCH_MAX_ATTEMPTS_EXCEEDED dicatat untuk merekamnya. Pada API Pencocokan Wajah mandiri, hanya ambang batas penolakan yang tersedia (opsi permintaan face_match_score_decline_threshold, default 30); setiap peringatan yang terpicu akan menolak permintaan, dan NO_REFERENCE_IMAGE terpicu jika tidak ada wajah yang dapat dibandingkan sama sekali.

Peringatan yang dihasilkan

Risiko	Penyebab	Tingkat keparahan	Memengaruhi status?	Remediasi
`LOW_FACE_MATCH_SIMILARITY`	`score` ≤ `face_match_score_review_threshold`. Tidak ditampilkan ketika `NO_REFERENCE_IMAGE` juga ada.	`warning` di antara ambang batas; `error` pada atau di bawah ambang batas penolakan	`In Review` di antara ambang batas; `Declined` pada atau di bawah ambang batas penolakan	Sesuaikan ambang batas, atau terima melalui peninjauan manual.
`FACE_MATCH_NOT_COMPUTED`	Skor kemiripan tidak dapat dihitung karena tidak ada wajah yang terdeteksi di foto wajah pada dokumen, atau karena langkah identitas berupa pencarian non-dokumen yang tidak meninggalkan referensi untuk dibandingkan (registri yang tidak mengembalikan foto dan tidak memeriksa wajah). Tidak ditampilkan ketika `NO_REFERENCE_IMAGE` juga ada.	`warning` saat `face_match_not_computed_action` adalah `REVIEW`; `error` saat `DECLINE`	`In Review` atau `Declined`, sesuai `face_match_not_computed_action`	Gambar dokumen tidak dapat diambil ulang pada langkah ini: selesaikan melalui peninjauan manual, atau ambil ulang dokumen lebih awal dalam alur. Setelah pencarian yang hanya menggunakan data, atur `face_match_not_computed_action` ke hasil yang Anda inginkan, atau wajibkan dokumen di negara-negara tempat pencocokan biometrik penting.
`NO_FACE_IN_SELFIE`	Skor kemiripan tidak dapat dihitung karena tidak ada wajah yang terdeteksi di swafoto pengguna. Pengguna diminta untuk mengambil ulang swafoto sebelum peringatan ini ditetapkan.	`warning` saat `face_match_not_computed_action` adalah `REVIEW`; `error` saat `DECLINE`	`In Review` atau `Declined`, sesuai `face_match_not_computed_action`, setelah kesempatan coba lagi habis	Pengguna mengambil ulang swafoto yang lebih jelas, berpenerangan baik, dan menghadap ke depan.
`NO_REFERENCE_IMAGE`	Gambar referensi atau gambar target tidak ada (kecuali referensi yang tidak pernah dihasilkan oleh pencarian non-dokumen, yaitu `FACE_MATCH_NOT_COMPUTED`).	`error`	Penolakan otomatis	Pastikan foto wajah pada dokumen dan swafoto liveness diambil. Untuk API mandiri, berikan dua gambar wajah yang valid.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	Pengguna menghabiskan kuota coba lagi pengambilan (`face_match_max_attempts`) setelah kegagalan kemiripan rendah yang berulang.	`information`	Tidak — mencatat bahwa status yang dihitung dari upaya terakhir (penolakan atau peninjauan) telah diterapkan	Tingkatkan `face_match_max_attempts` pada node alur kerja, atau selesaikan melalui peninjauan manual.

Contoh

Dalam Peninjauan — kemiripan yang berada di ambang batas

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face match similarity",
    "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
    "node_id": "feature_face_match_1"
  }
]

Dalam Peninjauan — Pencocokan Wajah tidak dapat dihitung

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_NOT_COMPUTED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Face match could not be computed",
    "long_description": "A face match score could not be computed because a face could not be detected in the document portrait. Because the document image cannot be recaptured, the result follows the configured action for this case (manual review by default) rather than being treated as a low-similarity mismatch.",
    "node_id": "feature_face_match_1"
  }
]

Penolakan otomatis — referensi hilang

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "NO_REFERENCE_IMAGE",
    "additional_data": null,
    "log_type": "error",
    "short_description": "No source image found for performing face match",
    "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
    "node_id": "feature_face_match_1"
  }
]

Percobaan ulang habis — status upaya terakhir diterapkan

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Low face match similarity",
    "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
    "node_id": "feature_face_match_1"
  },
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_MAX_ATTEMPTS_EXCEEDED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Maximum face match attempts exceeded",
    "long_description": "The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.",
    "node_id": "feature_face_match_1"
  }
]

API Pencocokan Wajah mandiri mengembalikan bentuk peringatan yang sama tanpa node_id (perbandingan tidak terikat pada suatu node alur kerja).

Jenis peringatan

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

Terkait

Laporan Pencocokan Wajah — skema laporan lengkap dan status.
Peringatan Deteksi Liveness — peringatan dari proses sebelumnya pada pengambilan swafoto.
Webhook — session.status.updated memuat peringatan segera setelah langkah selesai.
Model data — Pencocokan Wajah — skema kanonikal.
Model data — Objek peringatan — bentuk setiap entri dalam warnings[].

Autentikasi

Verifikasi

Pemantauan

Platform

Peringatan Pencocokan Wajah & Kode Error

Gambaran umum

Kondisi penolakan otomatis

Pengaturan verifikasi yang dapat dikonfigurasi

Peringatan yang dihasilkan

Contoh

Dalam Peninjauan — kemiripan yang berada di ambang batas

Dalam Peninjauan — Pencocokan Wajah tidak dapat dihitung

Penolakan otomatis — referensi hilang

Percobaan ulang habis — status upaya terakhir diterapkan

Jenis peringatan

Terkait

​Gambaran umum

​Kondisi penolakan otomatis

​Pengaturan verifikasi yang dapat dikonfigurasi

​Peringatan yang dihasilkan

​Contoh

​Dalam Peninjauan — kemiripan yang berada di ambang batas

​Dalam Peninjauan — Pencocokan Wajah tidak dapat dihitung

​Penolakan otomatis — referensi hilang

​Percobaan ulang habis — status upaya terakhir diterapkan

​Jenis peringatan

​Terkait

Gambaran umum

Kondisi penolakan otomatis

Pengaturan verifikasi yang dapat dikonfigurasi

Peringatan yang dihasilkan

Contoh

Dalam Peninjauan — kemiripan yang berada di ambang batas

Dalam Peninjauan — Pencocokan Wajah tidak dapat dihitung

Penolakan otomatis — referensi hilang

Percobaan ulang habis — status upaya terakhir diterapkan

Jenis peringatan

Terkait