> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros e diagnóstico

> Códigos de resposta do Antispoofing Facial, como distinguir um problema de captura de um problema de código, o que repetir e o que incluir em um chamado.

## Tabela de códigos

| Código | O que significa | De quem é o problema | Repetir? |
| - | - | - | - |
| `200` | Análise concluída. Leia `spoofing` para o veredito. | — | Não |
| `400` | A imagem não cumpre um requisito rígido. | Seu | Não |
| `401` | Api-key ausente, inválida ou de outro ambiente. | Seu | Não |
| `422` + `No Face Detected` | Nenhum rosto foi detectado na imagem. | Da captura | Não |
| `422` + `Bad request` e `detail[]` | O corpo da requisição não valida. | Seu | Não |
| `499` | O cliente encerrou a conexão. | Sua rede ou seu timeout | Sim |
| `500` | Erro do lado do serviço. | Depende — veja abaixo | Só se não for determinístico |

<Warning>
  **`200` não significa aprovado.** Significa que a análise foi concluída. Uma tentativa de falsificação detectada também responde `200`, com `spoofing: true`. A aprovação exige as duas condições: `status === 200 && spoofing === false`.
</Warning>

## Os dois `422`

O mesmo código cobre dois problemas completamente distintos, com dois donos distintos. **Distinga-os pela presença de `detail`, não pelo código HTTP.**

<CodeGroup>
  ```json Imagem sem rosto theme={null}
  {
    "code": 422,
    "spoofing": true,
    "message": "No Face Detected",
    "id": "89f3f57e-...",
    "info": "onboarding-12345",
    "date": "2026-08-20",
    "time": "16:57:09"
  }
  ```

  ```json Corpo inválido theme={null}
  {
    "id": "4b3501fb-...",
    "code": 422,
    "message": "Bad request",
    "detail": [
      {
        "type": "string_type",
        "loc": ["body", "info"],
        "msg": "Input should be a valid string",
        "input": { "ref": "onboarding-12345" }
      }
    ]
  }
  ```
</CodeGroup>

**Sem rosto** é um problema de captura: peça uma foto nova com instruções concretas — rosto centralizado, boa luz, nada na frente. Não é um bug e não se resolve repetindo a mesma imagem. Note que esta resposta traz `spoofing: true`: se o seu código aprova por exclusão, aqui ele aprova alguém cujo rosto nem chegou a ver.

**Corpo inválido** é um problema de código. `detail[].loc` diz exatamente qual campo está errado; no exemplo, `info` foi enviado como objeto quando o contrato pede uma cadeia. Resolve-se do seu lado e se reproduz sempre.

## `400`: a imagem não cumpre um requisito rígido

```json theme={null}
{
  "code": 400,
  "message": "Image should be larger than [224, 224]",
  "id": "f77e49f1-...",
  "info": "onboarding-12345"
}
```

Valide as dimensões antes de chamar. É mais rápido, mais barato e permite pedir ao usuário uma nova captura sem esperar a ida e volta.

## `401`: credenciais

```json theme={null}
{
  "statusCode": 401,
  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}
```

Note que este corpo usa `statusCode`, não `code`, e não traz `id`: é rejeitado antes de criar uma transação. Verifique se o cabeçalho se chama exatamente `Api-Key` e se a chave corresponde ao ambiente da URL base que você está usando. Misturar a chave de homologação com a URL de produção é a causa mais comum.

## `500`: nem todos são do serviço

Um `500` parece um problema do provedor, mas na prática a maioria é provocada pela requisição: dos cinco corpos `500` observados em testes, quatro tinham origem no pedido — uma imagem que o decodificador não conseguia processar, um payload malformado.

**O teste confiável é o determinismo:**

<Steps>
  <Step title="Repita a mesma requisição uma vez">
    Com o mesmo corpo, sem alterar nada.
  </Step>

  <Step title="Compare o erro">
    Se voltar **o mesmo** `error`, o problema está na sua requisição: revise a imagem e o payload. Se voltar diferente ou a chamada tiver êxito, foi transitório.
  </Step>

  <Step title="Se for determinístico, pare de repetir">
    Abra um chamado com o `id` e o corpo do erro. Repetir apenas adiciona carga.
  </Step>
</Steps>

## Política de novas tentativas

```js theme={null}
const REPETIVEL = (status, body) =>
  status === 499 ||
  (status === 500 && !/image|payload/i.test(body?.error ?? ""));

// No máximo 2 tentativas, com backoff exponencial. Nunca sobre spoofing: true.
```

<Warning>
  Nunca repita uma resposta `200` com `spoofing: true`. É um veredito, não uma falha. Uma nova tentativa que «conserta» uma rejeição está aprovando fraude.
</Warning>

## Abrir um chamado

Escreva para [customer.support@vusecurity.com](mailto:customer.support@vusecurity.com) com:

| Dado | Por quê |
| - | - |
| O `id` da transação | É a chave com que o suporte encontra o caso. Sem ele não há busca possível. |
| O ambiente | Homologação e produção podem rodar versões diferentes. |
| O carimbo de tempo aproximado | Delimita a janela de logs a revisar. |
| O corpo completo da resposta | Com `code`, `message` e `errorMessage` exatamente como chegaram. |

<Note>
  Não anexe a imagem original a menos que o suporte peça explicitamente e por um canal combinado: é um dado biométrico de uma pessoa real.
</Note>

<Card title="Voltar à introdução" icon="face-viewfinder" href="/pt/vucs/antispoofing-facial/introducao">
  A regra de decisão, os endpoints e a autenticação.
</Card>


## Related topics

- [Erros e diagnóstico](/pt/vucs/id-analysis/erros.md)
- [Guia de integração](/pt/vucs/face-analysis/integracao.md)
- [Integrar o Antispoofing Facial](/pt/vucs/antispoofing-facial/integracao.md)


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