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

# Pencarian Wajah 1:N: Peringatan & Kode Error

> Penjelasan kode peringatan Pencarian Wajah 1:N Didit: kecocokan daftar blokir, wajah duplikat, banyak wajah, dan penolakan gambar tanpa wajah.

## 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](https://docs.didit.me/id/core-technology/face-search/report-face-search.md)).

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`)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "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](https://docs.didit.me/id/core-technology/face-search/report-face-search.md) — bentuk respons lengkap
* [Referensi API Pencarian Wajah](https://docs.didit.me/id/standalone-apis/face-search.md) — parameter permintaan
* [Peringatan Pencocokan Wajah](https://docs.didit.me/id/core-technology/id-verification/warnings-id-verification.md) — peringatan swafoto-ke-dokumen 1:1 (terpisah dari Pencarian Wajah)
* [Model data — Pencarian Wajah](https://docs.didit.me/id/reference/data-models.md#pencarian-wajah) — skema kanonikal

### Jenis peringatan


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