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

# Erros e códigos

> Códigos HTTP, formatos de resposta e causas comuns dos erros da API

A API do Scanify retorna códigos HTTP padrão e, em caso de falha, um JSON descrevendo o erro. O formato do corpo depende do código.

## Códigos HTTP

| Código | Quando ocorre                                                  | Shape de resposta                                                                                         |
| ------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `200`  | Sucesso.                                                       | Ver [Payload de resposta](/response-payload).                                                             |
| `400`  | Erro de validação (corpo, formato, URL, segurança do arquivo). | `{ "message": "..." }`                                                                                    |
| `401`  | Chave de API ausente ou inválida.                              | `{ "error": "Unauthorized" }`                                                                             |
| `404`  | `requestId` informado não existe ou não pertence à conta.      | `{ "message": "Request not found" }`                                                                      |
| `408`  | Timeout do endpoint síncrono.                                  | `{ "success": false, "status": "failed", "code": "SYNC_TIMEOUT", "message": "...", "request_id": "..." }` |
| `500`  | Falha inesperada no servidor.                                  | `{ "message": "...", "request_id"?: "..." }`                                                              |

***

## 400 — Bad Request

Resposta:

```json theme={"dark"}
{
  "message": "Dados inválidos: ..."
}
```

Em endpoints que já criaram a requisição antes de falhar, o corpo pode incluir `request_id`.

Causas conhecidas:

* **Schema inválido (Zod)**: parâmetros faltando, tipos errados ou valores fora do range. Mensagem no formato `Dados inválidos: <detalhe do Zod>`.
* **`documentType` inválido**: valor não está na lista suportada. Veja [Tipos de documento](/document-types).
* **Arquivo + URL no mesmo request**: `Envie o arquivo ou a URL, não ambos.`
* **Nenhum arquivo enviado**: `Nenhum arquivo enviado.`
* **Arquivo vazio**: `Arquivo vazio.`
* **Formato não suportado**: `Formato de arquivo não suportado. Formatos aceitos: PDF, JPEG, PNG, TIFF, XML.`
* **XML em endpoint errado**: XML só é aceito em `/extract/sync` com `documentType=NFE`. Em `/classify`: `Classificação de XML não é suportada. Use /extract/sync com documentType=NFE.`
* **Arquivo bloqueado por segurança**: `Arquivo bloqueado pela validação de segurança.`
* **URL inválida**: `URL inválida.` ou `Protocolo de URL inválido.`
* **IP de destino bloqueado (SSRF)**: `Endereço IP não permitido.` — a URL resolveu para um IP privado, loopback ou link-local.
* **Download falhou**: `Não foi possível baixar o arquivo da URL fornecida.`
* **Arquivo excede o tamanho máximo**: `Arquivo excede o tamanho máximo permitido.`

***

## 401 — Unauthorized

```json theme={"dark"}
{
  "error": "Unauthorized"
}
```

Causas:

* Header `Authorization` ausente.
* Token presente mas chave de API inválida ou revogada.

Veja [Autenticação](/authentication) para o formato correto do header.

***

## 404 — Not Found

```json theme={"dark"}
{
  "message": "Request not found"
}
```

Retornado por `GET /extract/{requestId}` (e endpoints relacionados como `/markdown` e `/bounding-box`) quando o `requestId` não existe ou não pertence à conta dona da chave de API usada.

***

## 408 — Request Timeout

Exclusivo do endpoint síncrono `POST /extract/sync`.

```json theme={"dark"}
{
  "success": false,
  "status": "failed",
  "code": "SYNC_TIMEOUT",
  "message": "...",
  "request_id": "req_01H..."
}
```

O documento não terminou de processar dentro do `timeout` informado (padrão `60000` ms).

Recomendações:

* Aumente o parâmetro `timeout` no corpo da requisição (até o limite documentado).
* Para documentos grandes ou processamento em volume, use o fluxo assíncrono com `callbackUrl`. Veja [Fluxo de uso](/flow).
* A requisição continua processando — você pode consultar o status posteriormente em `GET /extract/{requestId}` usando o `request_id` retornado.

***

## 500 — Internal Server Error

```json theme={"dark"}
{
  "message": "Erro inesperado.",
  "request_id": "req_01H..."
}
```

`request_id` aparece se a requisição chegou a ser criada antes da falha.

Recomendações:

* Faça retry com backoff exponencial.
* Se persistir, contate o suporte com o `request_id`.

***

<Info>
  A lista completa de valores aceitos em `documentType` está em [Tipos de documento](/document-types).
</Info>