Avisos e códigos de erro do Face Match

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). 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:

O código risk: um identificador estável que você pode usar como referência no seu código.
O log_type: information, warning ou error, derivado dos limiares de pontuação de similaridade do seu fluxo.
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 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 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 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

"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

"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

"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

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

A API de Correspondência facial 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: esquema completo do relatório e status.
Avisos de prova de vida: avisos anteriores sobre a captura da selfie.
Webhooks: session.status.updated traz os avisos assim que a etapa é concluída.
Modelos de dados — Correspondência facial: esquema canônico.
Modelos de dados — Objeto de aviso: o formato de cada entrada em warnings[].

Autenticação

Verificação

Monitoramento

Plataforma

Avisos e códigos de erro do Face Match

Visão geral

Condições de recusa automática

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

Avisos gerados

Exemplos

Em revisão — similaridade limítrofe

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

Recusa automática — referência ausente

Novas tentativas esgotadas — status da última tentativa aplicado

Tipos de aviso

Relacionados

​Visão geral

​Condições de recusa automática

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

​Avisos gerados

​Exemplos

​Em revisão — similaridade limítrofe

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

​Recusa automática — referência ausente

​Novas tentativas esgotadas — status da última tentativa aplicado

​Tipos de aviso

​Relacionados

Visão geral

Condições de recusa automática

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

Avisos gerados

Exemplos

Em revisão — similaridade limítrofe

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

Recusa automática — referência ausente

Novas tentativas esgotadas — status da última tentativa aplicado

Tipos de aviso

Relacionados