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

# Pesquisa facial 1:N: avisos e códigos de erro

> Os avisos de Pesquisa facial 1:N da Didit cobrem listas de bloqueio, rostos duplicados, múltiplos rostos e imagens sem rosto.

## Visão geral

A Pesquisa facial emite um pequeno conjunto de avisos para que a sua equipa possa perceber **por que razão** uma pesquisa devolveu `Approved` ou `Declined`. Os avisos são devolvidos no array `face_search.warnings[]` da resposta a `POST /v3/face-search/` (consulte o [relatório da Pesquisa facial](https://docs.didit.me/pt/core-technology/face-search/report-face-search.md)).

Os avisos aqui utilizam um **formato reduzido** em comparação com os avisos de fluxo: não existe `node_id`. O contrato de resposta documentado declara cinco campos — `risk`, `additional_data`, `log_type`, `short_description`, `long_description` — e o payload de execução inclui adicionalmente `feature`, que é sempre `"LIVENESS"` neste endpoint.

## Avisos produzidos

| Risco | Causa | Gravidade (`log_type`) | Afeta o estado | Mitigação recomendada |
| - | - | - | - | - |
| `FACE_IN_BLOCKLIST` | A imagem de pesquisa correspondeu a um rosto na lista de bloqueio de rostos da sua aplicação acima do intervalo de similaridade de alta confiança. | `error` | Força `Declined`. | Rejeite o utilizador. Investigue a sessão associada através de `additional_data.blocklisted_session_id`. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Um rosto na lista de bloqueio correspondeu dentro do intervalo de similaridade inferior de "possível", abaixo do intervalo de alta confiança. | `error` | Força `Declined` na API autónoma de Pesquisa facial (mais rigorosa do que a verificação de prova de vida do fluxo, que envia este risco para análise). | Revisão manual. Confirme a correspondência com a evidência original da lista de bloqueio antes de agir. |
| `MULTIPLE_FACES_DETECTED` | Foi detetado mais do que um rosto na imagem de pesquisa enviada. A pesquisa continua a ser executada, utilizando o maior rosto detetado. | `warning` | Nenhum — nunca recusa por si só. | Volte a capturar com um único sujeito no enquadramento se o maior rosto não for o pretendido. |
| `DUPLICATED_FACE` | O rosto correspondeu, acima do intervalo de alta confiança, a um rosto de uma sessão **aprovada** ou a um rosto de perfil de utilizador importado. O endpoint autónomo não exclui sessões com o mesmo `vendor_data`, pelo que um utilizador recorrente corresponde às suas próprias sessões anteriores. | `information` | Nenhum — os duplicados são apresentados como sinal, não como recusas. | Investigue a sessão associada através de `additional_data.duplicated_session_id`. Decida se pretende bloquear ou fundir contas do seu lado. |
| `POSSIBLE_DUPLICATED_FACE` | O mesmo que `DUPLICATED_FACE`, mas a similaridade situa-se no intervalo inferior de "possível" em vez do intervalo de alta confiança. | `information` | Nenhum. | Revisão manual antes de tratar os dois registos como a mesma pessoa. |

Produtor: `FaceSearchAPIView.add_warnings` (`apis/views/face_search.py:250-330`); derivação de estado: `get_face_search_status` (`apis/views/face_search.py:242-248`), que recusa **apenas** para os dois riscos de lista de bloqueio.

Regras de emissão que convém conhecer:

* **A lista de bloqueio tem precedência sobre os duplicados.** Uma correspondência confirmada na lista de bloqueio suprime `DUPLICATED_FACE`, e uma possível correspondência na lista de bloqueio suprime `POSSIBLE_DUPLICATED_FACE` — nunca recebe ambos os membros de um par para o mesmo intervalo de confiança.
* **`additional_data` referencia apenas o primeiro rosto correspondente**, mesmo quando `matches[]` contém vários. Os avisos de lista de bloqueio contêm `{blocklisted_session_id, blocklisted_session_number, api_service}`; os avisos de duplicado contêm `{duplicated_session_id, duplicated_session_number, api_service}`; `MULTIPLE_FACES_DETECTED` contém `null`. O valor de `api_service` está em maiúsculas (por exemplo, `PASSIVE_LIVENESS`) ou `null` para sessões de fluxo.
* **Rostos na lista de permissões suprimem avisos de duplicado** — uma correspondência de alta confiança na lista de permissões anula `DUPLICATED_FACE`/`POSSIBLE_DUPLICATED_FACE` (nunca anula avisos de lista de bloqueio).

### Strings exatas dos avisos

| Risco | `short_description` | `long_description` |
| - | - | - |
| `FACE_IN_BLOCKLIST` | Rosto na lista de bloqueio | O sistema identificou um rosto na lista de bloqueio, o que significa que o rosto não tem permissão para ser verificado. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Possível rosto na lista de bloqueio | O sistema identificou um possível rosto na lista de bloqueio, o que significa que o rosto não tem permissão para ser verificado. |
| `DUPLICATED_FACE` | Rosto duplicado de outra sessão aprovada | O sistema identificou um rosto duplicado de outra sessão aprovada, exigindo investigação adicional. |
| `POSSIBLE_DUPLICATED_FACE` | Possível rosto duplicado de outra sessão aprovada | O sistema identificou um possível rosto duplicado de outra sessão aprovada, exigindo investigação adicional. |
| `MULTIPLE_FACES_DETECTED` | Múltiplos rostos detetados | Foram detetados múltiplos rostos na imagem de prova de vida. O sistema utiliza o maior rosto para a verificação de prova de vida e comparação facial, mas a presença de múltiplos rostos pode exigir uma revisão adicional. |

### Validação da imagem de pesquisa

Quando não é detetado nenhum rosto em `user_image`, a API rejeita o pedido com o código HTTP `400` e `{"error": "No face detected in the image"}` **antes** de um objeto `face_search` ser construído — pelo que um aviso `NO_FACE_DETECTED` nunca aparece numa resposta bem-sucedida da Pesquisa facial. Isto é devolvido como uma string de `error` de nível superior, e não em `warnings[]`.

## Definições configuráveis

Os intervalos de similaridade que separam correspondências confirmadas (`FACE_IN_BLOCKLIST`, `DUPLICATED_FACE`) de possíveis correspondências (`POSSIBLE_FACE_IN_BLOCKLIST`, `POSSIBLE_DUPLICATED_FACE`) são fixos internamente — o ajuste de limiares por aplicação aplica-se à verificação de prova de vida do fluxo, não a este endpoint. Os parâmetros que controla por pedido são:

* **`search_type`** (`most_similar`, predefinição | `blocklisted_or_approved`) — `most_similar` classifica cada rosto registado por similaridade; `blocklisted_or_approved` restringe os candidatos a rostos na lista de bloqueio, rostos na lista de permissões, rostos de sessões aprovadas e rostos de perfis de utilizador importados, classificando as entradas na lista de bloqueio em primeiro lugar.
* **`save_api_request`** (predefinição `true`) — persiste a chamada como uma sessão do tipo API e regista o rosto pesquisado no seu índice de pesquisa facial. Os rostos registados por chamadas de Pesquisa facial são excluídos de resultados futuros da Pesquisa facial. Defina como `false` para consultar sem armazenar ou registar.
* **`rotate_image`** (predefinição `false`) — tenta rotações de 90 graus e mantém a orientação com a melhor deteção facial; útil quando a orientação EXIF está ausente.

## Exemplos

### Correspondência na lista de bloqueio (força `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."
    }
  ]
}
```

### Sinal de duplicado (o estado permanece `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."
    }
  ]
}
```

## Relacionado

* [Relatório de Pesquisa facial](https://docs.didit.me/pt/core-technology/face-search/report-face-search.md) — formato completo da resposta
* [Referência da API de Pesquisa facial](https://docs.didit.me/pt/standalone-apis/face-search.md) — parâmetros do pedido
* [Avisos de Correspondência facial](https://docs.didit.me/pt/core-technology/id-verification/warnings-id-verification.md) — avisos de correspondência 1:1 entre selfie e documento (separados da Pesquisa facial)
* [Modelos de dados — Pesquisa facial](https://docs.didit.me/pt/reference/data-models.md#pesquisa-facial) — esquema canónico

### Tipos de aviso


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