Codigos de Erro

Entendendo as respostas de erro da API e como trata-las.

Visao Geral

A API retorna respostas de erro padronizadas com codigos de erro especificos para ajuda-lo a identificar e resolver problemas rapidamente.

Formato da Resposta de Erro

{
  "status": "error",
  "error": {
    "code": "AUTH_1001",
    "message": "Credenciais de autenticacao ausentes",
    "details": "Os campos 'username' e 'password' sao obrigatorios",
    "timestamp": "2025-12-22T10:30:00Z"
  }
}

Erros de Autenticacao (1000-1099)

Codigo	HTTP	Mensagem	Solucao
`AUTH_1001`	401	Credenciais de autenticacao ausentes	Inclua usuario e senha na requisicao
`AUTH_1002`	401	Usuario ou senha invalidos	Verifique se as credenciais estao corretas
`AUTH_1003`	403	Conta temporariamente bloqueada	Aguarde antes de tentar novamente ou entre em contato com o suporte

Erros de Cota (1100-1199)

Codigo	HTTP	Mensagem	Solucao
`QUOTA_1101`	403	Cota de API insuficiente	Compre mais creditos ou verifique a cota
`QUOTA_1102`	429	Cota de API excedida	Aguarde a renovacao da cota ou faca upgrade do plano

Erros de Validacao (2000-2099)

Codigo	HTTP	Mensagem	Solucao
`VAL_2001`	400	Nenhum arquivo enviado	Inclua um arquivo na requisicao
`VAL_2002`	400	Formato de arquivo invalido	Use formatos suportados: PDF, PNG, JPG, WEBP
`VAL_2003`	400	Multiplos arquivos PDF nao permitidos	Envie um unico PDF ou multiplas imagens
`VAL_2004`	400	PDF e imagens nao podem ser misturados	Envie PDF ou imagens, nao ambos

Erros de Processamento (3000-3099)

Codigo	HTTP	Mensagem	Solucao
`PROC_3001`	500	Falha no processamento do documento	Verifique a qualidade da imagem, tente novamente
`PROC_3006`	504	Timeout no processamento	Reduza o tamanho do arquivo ou divida em multiplas requisicoes

Erros do Servidor (5000-5099)

Codigo	HTTP	Mensagem	Solucao
`SRV_5001`	500	Erro interno do servidor	Tente novamente, entre em contato com o suporte se persistir
`SRV_5002`	503	Servico temporariamente indisponivel	Aguarde e tente novamente com backoff exponencial

Boas Praticas de Tratamento de Erros

Recomendacoes

Sempre verifique o campo status - Respostas de sucesso tem "status": "success"
Implemente logica de retry para erros transitorios (5xx) com backoff exponencial
Registre codigos de erro para depuracao e monitoramento
Exiba mensagens amigaveis baseadas nos codigos de erro