Códigos de Erro

Todas as respostas de erro da API seguem o mesmo formato:

{
  "error": "Mensagem descritiva do erro",
  "code": "CODIGO_DO_ERRO"
}

O campo code é estável e pode ser usado programaticamente para tratar erros. O campo error contém uma mensagem em português adequada para exibição ao usuário.

Autenticação

Código	HTTP	Descrição
`UNAUTHORIZED`	401	Credenciais inválidas ou ausentes. Verifique sua chave de API ou sessão.
`FORBIDDEN`	403	Acesso negado. O usuário não tem permissão para esta operação.
`ORG_REQUIRED`	403	Organização ativa é obrigatória. A chave de API deve estar associada a uma organização.

Rate Limiting

Código	HTTP	Descrição
`API_KEY_RATE_LIMITED`	429	Limite de requisições excedido. A resposta inclui um campo `tryAgainIn` (em milissegundos) indicando quando a janela será resetada.

{
  "error": "Limite de requisições excedido. Tente novamente mais tarde.",
  "code": "API_KEY_RATE_LIMITED",
  "tryAgainIn": 42350
}

O rate limit é compartilhado entre todas as chaves de API da mesma organização. O limite padrão é de 1000 requisições por minuto.

Agentes e Campos

Código	HTTP	Descrição
`AGENT_NOT_FOUND`	404	Agente não encontrado. Verifique o ID ou código do agente.
`AGENT_INACTIVE`	400	O agente está desativado e não aceita novas extrações.
`AGENT_NO_FIELDS`	400	O agente não possui campos configurados. Configure os campos antes de executar extrações.
`FIELD_NOT_FOUND`	404	Campo do agente não encontrado.

Extrações

Código	HTTP	Descrição
`EXTRACTION_NOT_FOUND`	404	Extração não encontrada. Verifique o ID ou código de rastreamento.
`EXTRACTION_FAILED`	500	A extração falhou durante o processamento. Tente novamente.
`FIELD_INFERENCE_FAILED`	500	Não foi possível sugerir campos automaticamente a partir do documento.

Arquivos e Documentos

Código	HTTP	Descrição
`FILE_INVALID`	400	O arquivo enviado é inválido ou está corrompido.
`FILE_TOO_LARGE`	400	O arquivo excede o tamanho máximo permitido.
`FILE_UNSUPPORTED`	400	O formato do arquivo não é suportado. Formatos aceitos: PNG, JPEG, WebP, GIF, PDF, texto.
`FILE_DOWNLOAD_FAILED`	500	Não foi possível acessar o arquivo enviado no armazenamento.
`INVALID_DOCUMENT`	400	O documento está vazio, corrompido ou não pode ser lido.

Provedor de IA

Estes erros ocorrem durante o processamento da extração pelo modelo de IA. A extração será marcada como error e o código será incluído no campo errorCode.

Código	HTTP	Descrição
`PROVIDER_ERROR`	500	Erro genérico do provedor de IA.
`PROVIDER_RATE_LIMIT`	429	O modelo de IA está sobrecarregado. A extração será retentada automaticamente com o modelo de fallback.
`PROVIDER_UNAVAILABLE`	503	O serviço de IA está temporariamente indisponível.
`PROVIDER_AUTH`	502	Falha na autenticação com o provedor de IA. Contate o suporte.
`PROVIDER_TIMEOUT`	503	O modelo de IA demorou demais para responder.
`PROVIDER_SCHEMA_MISMATCH`	500	O modelo retornou dados em formato inesperado. Ajuste os campos do agente.

Infraestrutura

Código	HTTP	Descrição
`QUEUE_ENQUEUE_FAILED`	500	Falha ao enfileirar a extração para processamento.
`STORAGE_ERROR`	500	Falha ao acessar o armazenamento de arquivos.
`DATABASE_ERROR`	500	Falha ao acessar o banco de dados.

Chaves de API

Código	HTTP	Descrição
`API_KEY_NOT_FOUND`	404	Chave de API não encontrada.

Convites

Código	HTTP	Descrição
`INVITATION_NOT_FOUND`	404	Convite não encontrado.
`INVITATION_EXPIRED`	410	O convite expirou (validade de 7 dias).
`INVITATION_ACCEPTED`	410	O convite já foi aceito.
`INVITATION_CANCELLED`	410	O convite foi cancelado.

Genérico

Código	HTTP	Descrição
`UNKNOWN_ERROR`	500	Erro inesperado. Tente novamente. Se persistir, contate o suporte.

Códigos de Erro

On this page