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

# Avisos e códigos de erro do Face Match

> Avisos do Face Match 1:1 da Didit — baixa similaridade, imagem de referência ausente, tentativas esgotadas — com causa, gravidade e solução.

## Visão geral

Os avisos do relatório de correspondência facial sinalizam cada condição que a Didit observou ao executar a comparação facial 1:1. Eles ficam no array `warnings[]` de cada item de `face_matches[]` (consulte [Relatório de correspondência facial](https://docs.didit.me/pt-br/core-technology/face-match/report-face-match.md)). Cada entrada também traz `feature: "FACEMATCH"` e o `node_id` do nó do fluxo de verificação (workflow) que gerou o aviso.

Todo aviso tem três camadas:

1. **O código `risk`**: um identificador estável que você pode usar como referência no seu código.
2. **O `log_type`**: `information`, `warning` ou `error`, derivado dos limiares de pontuação de similaridade do seu fluxo.
3. **O impacto na decisão**: definido pelos limiares de revisão e de recusa do fluxo para a pontuação de similaridade.

O módulo de correspondência facial é intencionalmente enxuto: há exatamente cinco códigos de risco, listados por completo abaixo.

## Condições de recusa automática

O risco a seguir sempre faz com que o relatório de correspondência facial (e a sessão) sejam definidos como `Declined`:

| Risco | Gatilho |
| - | - |
| `NO_REFERENCE_IMAGE` | Falta a `source_image` (referência) ou a `target_image` (selfie), portanto nenhuma comparação foi possível. |

Quando `NO_REFERENCE_IMAGE` é disparado, `LOW_FACE_MATCH_SIMILARITY` é suprimido (não há nada a pontuar).

Há uma exceção.
Quando a etapa de identidade foi concluída por uma [consulta sem documento](https://docs.didit.me/pt-br/core-technology/id-verification/non-doc-lookup.md) cujo registro não retorna retrato nem verifica rosto, a Correspondência facial, por definição, não tem com o que comparar a captura ao vivo.
Isso é informado como `FACE_MATCH_NOT_COMPUTED` com pontuação `null` e decidido por `face_match_not_computed_action` (abaixo), e não como uma recusa automática.

## Configurações de verificação ajustáveis

No console da Didit, a pontuação de similaridade da correspondência facial é controlada por dois limiares (não há opção Aprovar/Revisar/Recusar):

| Configuração | Padrão | Comportamento |
| - | - | - |
| `face_match_score_review_threshold` | 70 | Quando `score` ≤ este valor, `LOW_FACE_MATCH_SIMILARITY` é disparado e o status passa para `In Review`. |
| `face_match_score_decline_threshold` | 50 | Quando `score` ≤ este valor, o mesmo aviso é elevado para `error` e o status passa para `Declined`. |

Aumente o limiar de revisão se observar aprovações indevidas demais; reduza o limiar de recusa se observar recusas indevidas demais.

Uma configuração separada controla o que acontece quando uma pontuação de similaridade **não pode ser calculada de forma alguma**: nenhum rosto foi detectado em uma das imagens, ou uma consulta sem documento não deixou referência para comparação:

| Configuração | Padrão | Comportamento |
| - | - | - |
| `face_match_not_computed_action` | `REVIEW` | Ação aplicada quando o resultado "não foi possível calcular" é definitivo. `REVIEW` envia o relatório para `In Review`; `DECLINE` o define como `Declined`. (Não há opção de aprovação automática: uma pontuação que nunca foi calculada nunca é aprovada silenciosamente.) |

Essa ação rege `FACE_MATCH_NOT_COMPUTED` (nenhum rosto no retrato do documento, ou nenhuma referência após uma consulta sem documento) e `NO_FACE_IN_SELFIE` após o esgotamento das tentativas (nenhum rosto na selfie após as novas tentativas do usuário). Quando o problema é a selfie, primeiro o usuário é solicitado a capturá-la novamente (veja abaixo), e a ação só se aplica se ainda não for possível detectar um rosto quando o limite de tentativas se esgotar.

Falhas por baixa similaridade também entram em um ciclo de novas capturas antes de o status se tornar definitivo: o usuário tem até `face_match_max_attempts` tentativas no total (padrão 3, configurável de 2 a 5 por nó do fluxo) para capturar novamente. Uma falha `NO_FACE_IN_SELFIE` usa o mesmo ciclo de novas tentativas, já que capturar uma selfie mais nítida pode resolvê-la. Uma falha `FACE_MATCH_NOT_COMPUTED` **não** permite nova tentativa, pois o retrato do documento não pode ser capturado novamente nesta etapa. Somente quando o limite se esgota é que o status da última tentativa passa a valer, e `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` é registrado para documentar isso.

Na [API de Correspondência facial](https://docs.didit.me/pt-br/standalone-apis/face-match.md) independente, existe apenas um limiar de recusa (opção de requisição `face_match_score_decline_threshold`, padrão 30); qualquer aviso disparado recusa a requisição, e `NO_REFERENCE_IMAGE` é disparado quando nenhum rosto pôde ser comparado.

## Avisos gerados

| Risco | Causa | Severidade | Afeta o status? | Correção |
| - | - | - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | `score` ≤ `face_match_score_review_threshold`. Suprimido quando `NO_REFERENCE_IMAGE` também está presente. | `warning` entre os limiares; `error` no limiar de recusa ou abaixo dele | `In Review` entre os limiares; `Declined` no limiar de recusa ou abaixo dele | Ajuste os limiares ou aceite por meio de revisão manual. |
| `FACE_MATCH_NOT_COMPUTED` | Não foi possível calcular uma pontuação de similaridade porque nenhum rosto foi detectado no **retrato do documento**, ou porque a etapa de identidade foi uma [consulta sem documento](https://docs.didit.me/pt-br/core-technology/id-verification/non-doc-lookup.md) que não deixou nenhuma referência para comparação (um registro que não retorna retrato e não verifica nenhum rosto). Suprimido quando `NO_REFERENCE_IMAGE` também está presente. | `warning` quando `face_match_not_computed_action` é `REVIEW`; `error` quando é `DECLINE` | `In Review` ou `Declined`, conforme `face_match_not_computed_action` | A imagem do documento não pode ser recapturada nesta etapa: resolva por meio de revisão manual ou recapture o documento antes, no fluxo. Após uma consulta somente de dados, defina `face_match_not_computed_action` para o resultado desejado ou exija um documento nos países em que uma correspondência biométrica é importante. |
| `NO_FACE_IN_SELFIE` | Não foi possível calcular uma pontuação de similaridade porque nenhum rosto foi detectado na **selfie** do usuário. O usuário é solicitado a tirar outra selfie antes que esse aviso seja confirmado. | `warning` quando `face_match_not_computed_action` é `REVIEW`; `error` quando é `DECLINE` | `In Review` ou `Declined`, conforme `face_match_not_computed_action`, depois que as novas tentativas se esgotam | O usuário recaptura uma selfie mais nítida, bem iluminada e de frente. |
| `NO_REFERENCE_IMAGE` | A imagem de referência ou a imagem de destino está ausente (exceto uma imagem de referência que uma consulta sem documento nunca gerou, que corresponde a `FACE_MATCH_NOT_COMPUTED`). | `error` | **Recusa automática** | Garanta que tanto o retrato do documento quanto a selfie da prova de vida sejam capturados. Na API independente, envie duas imagens de rosto válidas. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | O usuário esgotou o limite de novas tentativas de captura (`face_match_max_attempts`) após falhas repetidas por baixa similaridade. | `information` | Não. Registra que o status calculado na última tentativa (recusa ou revisão) foi aplicado | Aumente `face_match_max_attempts` no nó do fluxo ou resolva por meio de revisão manual. |

## Exemplos

### Em revisão — similaridade limítrofe

```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"
  }
]
```

### Em revisão — não foi possível calcular a correspondência facial

```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"
  }
]
```

### Recusa automática — referência ausente

```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"
  }
]
```

### Novas tentativas esgotadas — status da última tentativa aplicado

```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]
>
> A [API de Correspondência facial](https://docs.didit.me/pt-br/standalone-apis/face-match.md) independente retorna o mesmo formato de aviso, sem `node_id` (a comparação não está vinculada a um nó do fluxo).

## Tipos de aviso

Cada risco recebe um nível de severidade com base na configuração da sua aplicação. As três severidades são:

## Relacionados

* [Relatório de correspondência facial](https://docs.didit.me/pt-br/core-technology/face-match/report-face-match.md): esquema completo do relatório e status.
* [Avisos de prova de vida](https://docs.didit.me/pt-br/core-technology/liveness/warnings-liveness.md): avisos anteriores sobre a captura da selfie.
* [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md): `session.status.updated` traz os avisos assim que a etapa é concluída.
* [Modelos de dados — Correspondência facial](https://docs.didit.me/pt-br/reference/data-models.md#correspondência-facial): esquema canônico.
* [Modelos de dados — Objeto de aviso](https://docs.didit.me/pt-br/reference/data-models.md#objeto-de-aviso): o formato de cada entrada em `warnings[]`.


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