> ## 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 de correspondência facial

> Conheça todos os avisos de correspondência facial 1:1 da Didit, incluindo baixa similaridade ou tentativas esgotadas, com causas e resolução.

## Visão geral

Os avisos no relatório de correspondência facial assinalam todas as condições que a Didit observou durante a comparação facial 1:1. Estes são incluídos no array `warnings[]` de cada item de `face_matches[]` (consulte [Relatório de correspondência facial](https://docs.didit.me/pt/core-technology/face-match/report-face-match.md)). Cada entrada contém também `feature: "FACEMATCH"` e o `node_id` do nó do fluxo que a originou.

Cada aviso tem três camadas:

1. **O código de `risk`** — um identificador estável com o qual pode fazer correspondência no seu código.
2. **O `log_type`** — `information`, `warning` ou `error`, derivado dos limiares de pontuação de semelhança 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 semelhança.

O módulo de correspondência facial é intencionalmente compacto — existem exatamente cinco códigos de risco, listados na íntegra abaixo.

## Condições de recusa automática

O seguinte risco força sempre o relatório de correspondência facial (e a sessão) para `Declined`:

| Risco | Acionador |
| - | - |
| `NO_REFERENCE_IMAGE` | Uma das imagens `source_image` (referência) ou `target_image` (selfie) está em falta, pelo que não foi possível realizar qualquer comparação. |

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

Existe uma exceção.
Quando o passo de identificação foi concluído através de uma [consulta sem documento](https://docs.didit.me/pt/core-technology/id-verification/non-doc-lookup.md) cujo registo não devolve qualquer retrato nem verifica nenhuma face, a Correspondência facial não tem, por conceção, qualquer imagem contra a qual comparar a captura em direto.
Isto é reportado como `FACE_MATCH_NOT_COMPUTED` com uma pontuação `null` e a decisão é determinada por `face_match_not_computed_action` (abaixo), e não como uma recusa automática.

## Definições de verificação configuráveis

Na consola da Didit, a pontuação de semelhança da correspondência facial é regulada por dois limiares (sem alternador de Aprovar/Revisão/Recusar):

| Definição | Predefinição | Comportamento |
| - | - | - |
| `face_match_score_review_threshold` | 70 | Quando `score` ≤ este valor, `LOW_FACE_MATCH_SIMILARITY` é acionado e o estado passa para `In Review`. |
| `face_match_score_decline_threshold` | 50 | Quando `score` ≤ este valor, o mesmo aviso escala para `error` e o estado passa para `Declined`. |

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

Uma definição separada controla o que acontece quando uma pontuação de semelhança **não pode ser calculada de todo**: nenhuma face foi detetada numa das imagens, ou uma consulta sem documento não deixou qualquer referência para comparação:

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

Esta ação rege `FACE_MATCH_NOT_COMPUTED` (ausência de face no retrato do documento ou ausência total de referência após uma consulta sem documento) e um `NO_FACE_IN_SELFIE` esgotado (nenhuma face na selfie após as novas tentativas do utilizador). Quando o problema é a selfie, pede-se primeiro ao utilizador que efetue uma nova captura — ver abaixo — e a ação só se aplica se ainda não for possível detetar uma face depois de esgotado o limite de tentativas.

As falhas por baixa semelhança também entram num ciclo de nova tentativa de captura antes de o estado se fixar: o utilizador tem até `face_match_max_attempts` tentativas totais (3 por predefinição, configurável de 2 a 5 por nó do fluxo) para recapturar. Uma falha de `NO_FACE_IN_SELFIE` utiliza o mesmo ciclo de tentativas, dado que recapturar uma selfie mais nítida pode resolver o problema. Uma falha de `FACE_MATCH_NOT_COMPUTED` **não** permite novas tentativas — o retrato do documento não pode ser recapturado neste passo. O estado da última tentativa só se aplica quando o limite de tentativas estiver esgotado — sendo registado `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`.

Na [API de Correspondência facial](https://docs.didit.me/pt/standalone-apis/face-match.md) autónoma existe apenas um limiar de recusa (opção de pedido `face_match_score_decline_threshold`, predefinição 30); qualquer aviso acionado recusa o pedido, e `NO_REFERENCE_IMAGE` é acionado quando não foi possível comparar nenhuma face.

## Avisos gerados

| Risco | Causa | Gravidade | Afeta o estado? | Resoluçã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` igual ou inferior ao limiar de recusa | `In Review` entre os limiares; `Declined` igual ou inferior ao limiar de recusa | Ajuste os limiares ou aprove através de revisão manual. |
| `FACE_MATCH_NOT_COMPUTED` | Não foi possível calcular uma pontuação de similaridade porque não foi detetado nenhum rosto no **retrato do documento**, ou porque o passo do documento foi uma [pesquisa sem documento](https://docs.didit.me/pt/core-technology/id-verification/non-doc-lookup.md) que não deixou qualquer referência com a qual comparar (um registo que não devolve nenhum 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`, de acordo com `face_match_not_computed_action` | A imagem do documento não pode ser recapturada neste passo: resolva através de revisão manual ou recapturando o documento mais cedo no fluxo. Após uma pesquisa apenas de dados, defina `face_match_not_computed_action` para o resultado pretendido, ou exija um documento em países onde a correspondência biométrica seja relevante. |
| `NO_FACE_IN_SELFIE` | Não foi possível calcular uma pontuação de similaridade porque não foi detetado nenhum rosto na **selfie** do utilizador. É pedido ao utilizador que tire novamente a selfie antes de este aviso se tornar definitivo. | `warning` quando `face_match_not_computed_action` é `REVIEW`; `error` quando é `DECLINE` | `In Review` ou `Declined`, de acordo com `face_match_not_computed_action`, após o esgotamento das tentativas | O utilizador volta a capturar uma selfie mais nítida, bem iluminada e de frente. |
| `NO_REFERENCE_IMAGE` | A imagem de referência ou a imagem de destino está em falta (exceto no caso de uma referência que uma pesquisa sem documento nunca tenha produzido, o que corresponde a `FACE_MATCH_NOT_COMPUTED`). | `error` | **Recusa automática** | Garanta que tanto o retrato do documento como a selfie de prova de vida são capturados. Para a API autónoma, forneça duas imagens de rosto válidas. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | O utilizador esgotou o limite de novas tentativas de captura (`face_match_max_attempts`) após falhas repetidas por baixa similaridade. | `information` | Não — regista que o estado calculado da última tentativa (recusa ou revisão) foi aplicado | Aumente `face_match_max_attempts` no nó do fluxo ou resolva através de revisão manual. |

## Exemplos

### Em análise — similaridade no limiar

```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 análise — 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 em falta

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

### Tentativas esgotadas — estado 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 [Face Match API](https://docs.didit.me/pt/standalone-apis/face-match.md) autónoma devolve o mesmo formato de aviso, exceto `node_id` (a comparação não está vinculada a um nó de fluxo).

## Tipos de aviso

É atribuída uma gravidade a cada risco com base na configuração da sua aplicação. As três gravidades são:

## Relacionado

* [Relatório de correspondência facial](https://docs.didit.me/pt/core-technology/face-match/report-face-match.md) — esquema e estados completos do relatório.
* [Avisos de prova de vida](https://docs.didit.me/pt/core-technology/liveness/warnings-liveness.md) — avisos a montante na captura da selfie.
* [Webhooks](https://docs.didit.me/pt/integration/webhooks.md) — `session.status.updated` transmite os avisos assim que o passo termina.
* [Modelos de dados — Correspondência facial](https://docs.didit.me/pt/reference/data-models.md#correspondência-facial) — esquema canónico.
* [Modelos de dados — Objeto de aviso](https://docs.didit.me/pt/reference/data-models.md#objeto-de-aviso) — a estrutura de cada entrada em `warnings[]`.


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