> ## 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 Pencocokan Wajah & Kode Error

> Semua peringatan modul pencocokan wajah 1:1 Didit beserta penyebab, keparahan, dan solusi saat kemiripan rendah atau batas coba lagi habis.

## 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](https://docs.didit.me/id/core-technology/face-match/report-face-match.md)). Setiap entri juga memuat `feature: "FACEMATCH"` dan `node_id` dari node alur kerja yang memunculkannya.

Setiap peringatan memiliki tiga lapisan:

1. **Kode `risk`** — pengidentifikasi stabil yang dapat Anda cocokkan di kode Anda.
2. **`log_type`** — `information`, `warning`, atau `error`, yang diperoleh dari ambang batas skor kemiripan alur kerja Anda.
3. **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](https://docs.didit.me/id/core-technology/id-verification/non-doc-lookup.md) 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](https://docs.didit.me/id/standalone-apis/face-match.md) 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](https://docs.didit.me/id/core-technology/id-verification/non-doc-lookup.md) 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

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

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

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

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

> [!NOTE]
>
> [API Pencocokan Wajah](https://docs.didit.me/id/standalone-apis/face-match.md) 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](https://docs.didit.me/id/core-technology/face-match/report-face-match.md) — skema laporan lengkap dan status.
* [Peringatan Deteksi Liveness](https://docs.didit.me/id/core-technology/liveness/warnings-liveness.md) — peringatan dari proses sebelumnya pada pengambilan swafoto.
* [Webhook](https://docs.didit.me/id/integration/webhooks.md) — `session.status.updated` memuat peringatan segera setelah langkah selesai.
* [Model data — Pencocokan Wajah](https://docs.didit.me/id/reference/data-models.md#pencocokan-wajah) — skema kanonikal.
* [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.