> ## 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 ID Analysis, o 422 que ecoa a sua solicitação inteira, o formato 401/404 do gateway 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 análise rodou. **Não** é uma aprovação: verifique `message`, `id` e as validações do verso. | Aplicar a regra de decisão. |
| `400` | Serviço | Um problema com a captura ou com o vínculo: imagem pequena demais, não decodificável, sem documento, `relatedUuid` ruim. | Corrigir a captura ou o vínculo. |
| `401` | Gateway | Falta o `Api-Key` ou a chave não vale para este ambiente. | Verificar chave e ambiente. |
| `404` | Gateway | Rota inexistente **ou método HTTP errado** (um `GET /front` devolve 404, não 405). Também um template desconhecido no catálogo. | Verificar rota e método. |
| `422` | Serviço | Violação do contrato: `info` ausente, `image` ausente, corpo malformado. **O erro ecoa a sua solicitação.** | Corrigir o corpo. |
| `500` | Serviço | Um erro transitório — ou um determinístico causado pela sua solicitação (`relatedUuid` em `/front`). | Ver a seção dos 500. |
| `503` | Serviço | O motor de OCR está fora do ar. | Repetir mais tarde com backoff. |

## As mensagens de `400`

| Mensagem | Causa |
| - | - |
| `Image is too small ...` | Abaixo de 480 × 480 (a mensagem informa altura × largura). |
| `Image is not a valid` | O base64 não decodifica para uma imagem. |
| `No document detected` | A captura não tem um documento reconhecível. Peça outra captura. |
| `relatedUuid or documentId is required` | `/back` sem `relatedUuid`. **A mensagem engana**: só `relatedUuid` vincula a transação; `documentId` não o substitui. |
| `Bad relatedUuid` | O `relatedUuid` não corresponde a uma frente registrada. Se acontecer **imediatamente** depois de uma frente bem-sucedida, espere um segundo e repita **uma vez** (atraso de replicação); se persistir, o valor está errado. |
| `Document is too close to the borders` | Com `strictBorderMode`: o documento está cortado. Peça outra captura. |

Os corpos de erro se parecem com isto:

```json theme={null}
{
  "uuid": "0f3f4a51-...",
  "code": 400,
  "message": "No document detected"
}
```

<Note>
  O `uuid` de um corpo de erro é **gerado na hora** e não corresponde a nenhuma transação — não serve como `relatedUuid` e o suporte não consegue consultá-lo.
</Note>

## O 422 ecoa a sua solicitação inteira — imagem incluída

O campo `detail[].input` do erro de validação é o **eco literal** do que você enviou, imagem base64 incluída, então um 422 pode pesar tanto quanto a solicitação:

```json theme={null}
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "info"],
      "msg": "Field required",
      "input": { "image": "/9j/4AAQSkZJRgABAQAAAQABAAD...v9Un0ooqDE//2Q==" }
    }
  ]
}
```

<Warning>
  **Nunca registre corpos de erro crus.** Um 422 logado persiste a foto do documento de uma pessoa real nos seus logs. Registre o código, a mensagem e o caminho do campo — nunca `input`.
</Warning>

## Os erros do gateway: outro formato

O `401` e o `404` vêm do gateway, com `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"
  }
  ```

  ```json 404 template desconhecido theme={null}
  {
    "code": 404,
    "message": "Template 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 `500`

Um `500` é determinístico e seu: **enviar `relatedUuid` em `/front`**. Ele se reproduz idêntico a cada tentativa — não repita; remova o campo. Qualquer outro `500` é transitório: repita com backoff, no máximo 2 vezes. O teste de determinismo é o de sempre: se a repetição devolve o erro idêntico, a causa é a sua solicitação.

O `healthCheck` pode devolver `408` enquanto `/version` ainda responde `"Service OK"` — trate como um aviso de degradação, não como indisponibilidade. Um `503` significa que o motor de OCR está fora do ar: nada a corrigir do seu lado; repita mais tarde.

## Se precisar abrir um chamado

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

| Dado | Onde está |
| - | - |
| O `uuid` da transação | No corpo `200` de `/front` (também no cabeçalho `x-request-id`). |
| O ambiente | Homologação ou produção. |
| Data e hora aproximadas | Com fuso horário. |
| O código HTTP e a mensagem | **Sem** o `detail` de um `422`, que contém a imagem. |

<Note>
  Proteção de dados: nunca anexe fotos de documentos nem corpos de resposta crus a um chamado, a menos que o suporte peça explicitamente por um canal seguro.
</Note>

<Card title="Voltar à introdução" icon="id-card" href="/pt/vucs/id-analysis/introducao">
  A regra de decisão, os três identificadores e o mapa de endpoints do ID Analysis.
</Card>


## Related topics

- [Erros e diagnóstico](/pt/vucs/face-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.