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

# Erros e Autenticação

> Formato das respostas de erro, autenticação por API key e catálogo de códigos

## Autenticação

Todas as rotas da API exigem o header `x-api-key` com a chave do seu projeto.

```bash theme={"theme":"catppuccin-latte"}
x-api-key: {sua_api_key}
```

Para gerar e gerenciar suas chaves, consulte [Autenticação API](/plataforma/autenticacao-api).

Quando a chave está ausente ou não é aceita, a resposta é `401` com `error` igual a `UNAUTHORIZED`:

| `message`                                                               | Quando ocorre                                             |
| :---------------------------------------------------------------------- | :-------------------------------------------------------- |
| `Missing x-api-key header or Bearer token authentication headers (...)` | O header `x-api-key` não foi enviado                      |
| `Invalid API key`                                                       | A chave enviada é inválida, expirou ou não foi encontrada |

## Formato do erro

As respostas de erro seguem um envelope padrão:

```json theme={"theme":"catppuccin-latte"}
{
  "error": "NOT_FOUND",
  "message": "Document not found",
  "requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
  "timestamp": "2026-06-01T12:00:00.000Z"
}
```

<ResponseField name="error" type="string">
  Código do erro. É um valor estável e enumerável — use-o para tratar o erro na sua integração.
</ResponseField>

<ResponseField name="message" type="string">
  Descrição legível do erro, muitas vezes montada com detalhes do caso (nome do campo, tipo de arquivo, tamanho).

  <Warning>
    Use o `message` apenas para diagnóstico e logs. Não baseie lógica na leitura do texto, pois ele pode mudar. Para ramificar o comportamento, use sempre o campo `error`.
  </Warning>
</ResponseField>

<ResponseField name="requestId" type="string">
  Identificador da requisição, útil para correlacionar logs e acionar o suporte.
</ResponseField>

<ResponseField name="timestamp" type="datetime">
  Data e hora em que o erro foi gerado.
</ResponseField>

## Códigos de erro

| `error`                   | HTTP | Quando ocorre                                                      |
| :------------------------ | :--- | :----------------------------------------------------------------- |
| `UNAUTHORIZED`            | 401  | API key ausente, inválida ou expirada                              |
| `INVALID_WORKFLOW_PRESET` | 400  | `workflowPresetAlias` fora dos valores aceitos                     |
| `FLEXIMAGE_IMPORT_FAILED` | 400  | Arquivo enviado inválido no envio de documentos                    |
| `FLEXIMAGE_IMPORT_FAILED` | 502  | Falha na integração ao enviar o documento                          |
| `NOT_FOUND`               | 404  | Documento não encontrado no escopo do projeto                      |
| `FILES_NOT_AVAILABLE`     | 422  | Arquivos ainda não disponíveis — documento sem `backofficeBatchId` |
| `FACE_NOT_AVAILABLE`      | 422  | Face ainda não disponível — documento sem `backofficeBatchId`      |
| `FLEXIMAGE_ERROR`         | 502  | Falha ao buscar arquivos ou face                                   |
| `INTERNAL_ERROR`          | 500  | Erro interno inesperado                                            |
| `INTERNAL_SERVER_ERROR`   | 500  | Erro interno inesperado nas rotas de parâmetros                    |

## FLEXIMAGE\_IMPORT\_FAILED: 400 e 502

O mesmo código aparece em duas situações com tratamentos opostos:

<AccordionGroup>
  <Accordion title="400 — arquivo inválido" icon="triangle-alert">
    O problema está no que foi enviado. Corrija o payload antes de tentar de novo. Causas comuns:

    * O arquivo não está em data URI (`data:image/jpeg;base64,...`)
    * Tipo não permitido para o campo (selfie não aceita PDF)
    * Conteúdo base64 vazio ou inválido
    * Conteúdo do arquivo não corresponde ao tipo declarado
    * Arquivo acima de **10 MB**
  </Accordion>

  <Accordion title="502 — falha de integração" icon="server">
    O envio falhou na comunicação com o serviço de processamento. Não é um erro do payload. Tente novamente com backoff e, se persistir, acione o suporte com o `requestId`.
  </Accordion>
</AccordionGroup>