Erros e códigos

​

Códigos HTTP

​

400 — Bad Request

{
  "message": "Dados inválidos: ..."
}

• 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.
• 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

{
  "error": "Unauthorized"
}

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

​

404 — Not Found

{
  "message": "Request not found"
}

​

408 — Request Timeout

{
  "success": false,
  "status": "failed",
  "code": "SYNC_TIMEOUT",
  "message": "...",
  "request_id": "req_01H..."
}

• 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.
• A requisição continua processando — você pode consultar o status posteriormente em GET /extract/{requestId} usando o request_id retornado.

​

500 — Internal Server Error

{
  "message": "Erro inesperado.",
  "request_id": "req_01H..."
}

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