Pencarian Wajah 1:N: Peringatan & Kode Error

Gambaran umum

Pencarian Wajah menghasilkan serangkaian kecil peringatan sehingga tim Anda dapat mengetahui mengapa suatu pencarian mengembalikan Approved atau Declined. Peringatan dikembalikan dalam larik face_search.warnings[] dari respons POST /v3/face-search/ (lihat Laporan Pencarian Wajah). Peringatan di sini menggunakan bentuk yang disederhanakan dibandingkan dengan peringatan alur kerja: tidak ada node_id. Kontrak respons yang terdokumentasi mendeklarasikan lima kolom — risk, additional_data, log_type, short_description, long_description — dan payload runtime juga memuat feature, yang selalu bernilai "LIVENESS" pada endpoint ini.

Peringatan yang dihasilkan

Risiko	Penyebab	Tingkat keparahan (`log_type`)	Memengaruhi status	Remediasi yang disarankan
`FACE_IN_BLOCKLIST`	Gambar pencarian cocok dengan wajah di daftar blokir wajah aplikasi Anda di atas rentang kemiripan dengan keyakinan tinggi.	`error`	Memaksa `Declined`.	Tolak pengguna. Selidiki sesi tertaut melalui `additional_data.blocklisted_session_id`.
`POSSIBLE_FACE_IN_BLOCKLIST`	Wajah dalam daftar blokir cocok dalam rentang kemiripan “mungkin” yang lebih rendah, di bawah rentang keyakinan tinggi.	`error`	Memaksa `Declined` pada API Pencarian Wajah mandiri (lebih ketat daripada pemeriksaan liveness alur kerja, yang mengarahkan risiko ini ke peninjauan).	Peninjauan manual. Konfirmasikan kecocokan terhadap bukti daftar blokir asli sebelum mengambil tindakan.
`MULTIPLE_FACES_DETECTED`	Lebih dari satu wajah ditemukan dalam gambar pencarian yang dikirimkan. Pencarian tetap berjalan, menggunakan wajah terbesar yang terdeteksi.	`warning`	Tidak ada — tidak pernah menolak dengan sendirinya.	Ambil ulang gambar dengan satu subjek dalam bingkai jika wajah terbesar bukanlah wajah yang dimaksud.
`DUPLICATED_FACE`	Wajah cocok, di atas batas keyakinan tinggi, dengan wajah dari sesi yang disetujui atau wajah profil pengguna yang diimpor. Endpoint mandiri tidak mengecualikan sesi dengan `vendor_data` yang sama, sehingga pengguna lama cocok dengan sesi mereka sebelumnya.	`information`	Tidak ada — duplikat dimunculkan sebagai sinyal, bukan penolakan.	Selidiki sesi tertaut melalui `additional_data.duplicated_session_id`. Putuskan apakah akan memblokir atau menggabungkan akun di pihak Anda.
`POSSIBLE_DUPLICATED_FACE`	Sama seperti `DUPLICATED_FACE` tetapi kemiripannya berada di rentang “mungkin” yang lebih rendah daripada rentang keyakinan tinggi.	`information`	Tidak ada.	Lakukan peninjauan manual sebelum menganggap kedua catatan tersebut merujuk pada orang yang sama.

Produsen: FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330); penentuan status: get_face_search_status (apis/views/face_search.py:242-248), yang menolak hanya untuk dua risiko daftar blokir. Aturan emisi yang perlu diketahui:

Daftar blokir lebih diprioritaskan daripada duplikat. Kecocokan daftar blokir yang terkonfirmasi menyembunyikan DUPLICATED_FACE, dan kemungkinan kecocokan daftar blokir menyembunyikan POSSIBLE_DUPLICATED_FACE — Anda tidak pernah mendapatkan kedua anggota pasangan untuk rentang keyakinan yang sama.
additional_data hanya merujuk pada wajah pertama yang cocok, bahkan ketika matches[] berisi beberapa wajah. Peringatan daftar blokir memuat {blocklisted_session_id, blocklisted_session_number, api_service}; peringatan duplikat memuat {duplicated_session_id, duplicated_session_number, api_service}; MULTIPLE_FACES_DETECTED memuat null. Nilai api_service berhuruf besar (misalnya PASSIVE_LIVENESS) atau null untuk sesi alur kerja.
Wajah yang masuk daftar izin menyembunyikan peringatan duplikat — kecocokan daftar izin berkeyakinan tinggi menghapus DUPLICATED_FACE/POSSIBLE_DUPLICATED_FACE (ini tidak pernah menghapus peringatan daftar blokir).

String peringatan persis

Risiko	`short_description`	`long_description`
`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.
`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.
`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.

Pemeriksaan gambar pencarian

Ketika tidak ada wajah yang terdeteksi di user_image, API menolak permintaan dengan HTTP 400 dan {"error": "No face detected in the image"} sebelum objek face_search dibuat — sehingga peringatan NO_FACE_DETECTED tidak pernah muncul dalam respons Pencarian Wajah yang berhasil. Ini dikembalikan sebagai string error tingkat atas, bukan di warnings[].

Pengaturan yang dapat dikonfigurasi

Rentang kemiripan yang memisahkan kecocokan terkonfirmasi (FACE_IN_BLOCKLIST, DUPLICATED_FACE) dari kemungkinan kecocokan (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) ditetapkan secara internal — penyesuaian ambang batas per aplikasi berlaku untuk pemeriksaan liveness alur kerja, bukan endpoint ini. Opsi yang dapat Anda kontrol pada setiap permintaan adalah:

search_type (most_similar, default | blocklisted_or_approved) — most_similar mengurutkan setiap wajah yang terdaftar berdasarkan kemiripan; blocklisted_or_approved membatasi kandidat pada wajah yang masuk daftar blokir, wajah yang masuk daftar izin, wajah dari sesi yang disetujui, dan wajah profil pengguna yang diimpor, dengan mengurutkan entri yang masuk daftar blokir terlebih dahulu.
save_api_request (default true) — menyimpan panggilan sebagai sesi bertipe API dan mendaftarkan wajah yang dicari ke dalam indeks pencarian wajah Anda. Wajah yang didaftarkan oleh panggilan Pencarian Wajah dikecualikan dari hasil Pencarian Wajah di masa mendatang. Atur ke false untuk melakukan kueri tanpa menyimpan atau mendaftarkan.
rotate_image (default false) — mencoba rotasi 90 derajat dan mempertahankan orientasi dengan deteksi wajah terbaik; berguna saat orientasi EXIF tidak ada.

Contoh

Temuan daftar blokir (memaksa `Declined`)

{
  "warnings": [
    {
      "risk": "FACE_IN_BLOCKLIST",
      "feature": "LIVENESS",
      "additional_data": {
        "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "blocklisted_session_number": 323442,
        "api_service": "PASSIVE_LIVENESS"
      },
      "log_type": "error",
      "short_description": "Face in blocklist",
      "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
    }
  ]
}

Sinyal duplikat (status tetap `Approved`)

{
  "warnings": [
    {
      "risk": "MULTIPLE_FACES_DETECTED",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "warning",
      "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."
    },
    {
      "risk": "DUPLICATED_FACE",
      "feature": "LIVENESS",
      "additional_data": {
        "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "duplicated_session_number": 1024,
        "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."
    }
  ]
}

Terkait

Laporan Pencarian Wajah — bentuk respons lengkap
Referensi API Pencarian Wajah — parameter permintaan
Peringatan Pencocokan Wajah — peringatan swafoto-ke-dokumen 1:1 (terpisah dari Pencarian Wajah)
Model data — Pencarian Wajah — skema kanonikal

Autentikasi

Verifikasi

Pemantauan

Platform

Pencarian Wajah 1:N: Peringatan & Kode Error

Gambaran umum

Peringatan yang dihasilkan

String peringatan persis

Pemeriksaan gambar pencarian

Pengaturan yang dapat dikonfigurasi

Contoh

Temuan daftar blokir (memaksa `Declined`)

Sinyal duplikat (status tetap `Approved`)

Terkait

Jenis peringatan

​Gambaran umum

​Peringatan yang dihasilkan

​String peringatan persis

​Pemeriksaan gambar pencarian

​Pengaturan yang dapat dikonfigurasi

​Contoh

​Temuan daftar blokir (memaksa Declined)

​Sinyal duplikat (status tetap Approved)

​Terkait

​Jenis peringatan

Gambaran umum

Peringatan yang dihasilkan

String peringatan persis

Pemeriksaan gambar pencarian

Pengaturan yang dapat dikonfigurasi

Contoh

Temuan daftar blokir (memaksa `Declined`)

Sinyal duplikat (status tetap `Approved`)

Terkait

Jenis peringatan