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

> Os códigos de erro do Face Analysis, os 500 com corpo em texto puro, o aborto de lote com imageNumber e quais erros podem ser repetidos.

## Os códigos, de relance

| Código | Emitido por | O que significa | O que fazer |
| - | - | - | - |
| `200` | Serviço | A operação rodou. **Não** implica match nem boa qualidade: avalie `biometric` e `inferenceConfidence`. | Aplicar a regra de decisão. |
| `400` | Serviço | Um problema com uma imagem ou operação específica: sem rosto, pequena demais, base64 inválido, operação inexistente. | Corrigir a imagem ou operação indicada. Não repetir igual. |
| `401` | Gateway | Falta o cabeçalho `Api-Key` ou a chave não vale para este ambiente. | Verificar chave e ambiente. |
| `404` | Gateway | Rota inexistente **ou método errado** (um `GET /inference` devolve 404, não 405). | Verificar rota e método. |
| `422` | Serviço | O corpo não é JSON válido, não é um objeto, ou `info` viola o formato. | Corrigir o corpo. |
| `500` | Serviço | Ou um erro transitório, ou **a sua solicitação**: `images` ausente ou `operations` desalinhado. Corpo em **texto puro**. | Ver a seção dos 500. |

## Os `400`: um único erro, com índice

O corpo do `400` aponta a imagem culpada com `imageNumber` (base 0):

```json theme={null}
{
  "id": "7be2f9a1-...",
  "code": 400,
  "message": "Face not found",
  "imageNumber": 1
}
```

| Mensagem | Causa |
| - | - |
| `Face not found` | Nenhum rosto foi detectado na imagem indicada. Peça outra captura. |
| `Image is too small` | A imagem está abaixo do mínimo rígido de 160 × 160 px. |
| `Image is not valid` | O conteúdo de `images[i]` não é base64 decodificável. |
| `Operation is not valid` | Um nome de operação não existe, ou você enviou `operations` como lista simples em vez de lista de listas. |

<Warning>
  **Uma imagem ruim aborta o lote inteiro.** Se você envia 4 imagens e a terceira não tem rosto, recebe um único `400` com `imageNumber: 2` e **nenhum** resultado — não há resultados parciais. Se o seu fluxo tolera falhas por imagem, envie uma solicitação por imagem.
</Warning>

## Os `500` vêm em texto puro

Dois erros de solicitação não devolvem um `400` arrumado, mas um `500` com o corpo literal `Internal Server Error` — **não é JSON**:

1. Omitir o campo `images`.
2. Enviar uma lista `operations` mais curta que `images`.

O seu cliente HTTP não deve assumir que toda resposta é JSON: envolva o parsing e trate a falha de parsing como erro, nunca como aprovação.

**Como distinguir um 500 transitório de um seu:** repita uma vez com backoff. Se voltar idêntico, é determinístico — a causa é a sua solicitação; valide `images` e o alinhamento de `operations` no seu código e pare de repetir.

## Os erros do gateway: outro formato

O `401` e o `404` não são emitidos pelo serviço, mas pelo gateway, e o corpo deles tem **outro formato** (`statusCode` em vez de `code`):

<CodeGroup>
  ```json 401 sem Api-Key theme={null}
  {
    "statusCode": 401,
    "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
  }
  ```

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

  ```json 404 rota ou método theme={null}
  {
    "statusCode": 404,
    "message": "Resource not found"
  }
  ```
</CodeGroup>

<Note>
  Um `401` com uma chave que «sempre funcionou» costuma ser mistura de ambientes: a chave de homologação contra a URL de produção ou vice-versa. Verifique o par URL + chave antes de escalar.
</Note>

## Os `422`: violações do contrato

Corpo não-JSON, corpo que não é um objeto, ou `info` fora do intervalo (2–256 caracteres) devolvem `422` com o detalhe campo a campo em `detail`. São erros de programação, não de dados: corrija-os em desenvolvimento, não os trate em produção.

## Política de novas tentativas

| Erro | Repetir? |
| - | - |
| `500` esporádico (não se repete idêntico) | Sim, com backoff, no máximo 2. |
| `500` determinístico | Não: corrigir a solicitação. |
| `400` / `401` / `404` / `422` | Não: corrigir imagem, credencial, rota ou corpo. |
| No-match (`200` com pontuação baixa) | **Nunca** com a mesma imagem: o resultado é determinístico. Peça outra captura. |
| `spoofing: true` | **Nunca** com a mesma imagem. |

## Se precisar abrir um chamado

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

| Dado | Onde está |
| - | - |
| O `id` da transação | No corpo da resposta (também presente nos `400`). |
| O ambiente | Homologação ou produção. |
| Data e hora aproximadas | Com fuso horário. |
| O código HTTP e a mensagem | Sem anexar imagens base64 nem corpos crus com dados pessoais. |

<Card title="Voltar à introdução" icon="user-check" href="/pt/vucs/face-analysis/introducao">
  A regra de decisão, os endpoints e o mapa de operações do Face Analysis.
</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.