Códigos de erro da API de análises de sangue

Última atualização: 8 de setembro de 2026

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

Visão Geral

A API retorna respostas de erro padronizadas com códigos de erro específicos para ajudá-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 Autenticação (1000-1099)

Código	HTTP	Mensagem	Solução
`AUTH_1001`	401	Credenciais de autenticação ausentes	Inclua usuário e senha na requisição
`AUTH_1002`	401	Usuário ou senha inválidos	Verifique se as credenciais estão corretas
`AUTH_1003`	403	Conta temporariamente bloqueada	Aguarde antes de tentar novamente ou entre em contato com o suporte

Erros de Cota (1100-1199)

Código	HTTP	Mensagem	Solução
`QUOTA_1101`	403	Cota de API insuficiente	Compre mais créditos ou verifique a cota
`QUOTA_1102`	429	Cota de API excedida	Aguarde a renovação da cota ou faca upgrade do plano

Erros de Validação (2000-2099)

Código	HTTP	Mensagem	Solução
`VAL_2001`	400	Nenhum arquivo enviado	Inclua um arquivo na requisição
`VAL_2002`	400	Formato de arquivo inválido	Use formatos suportados: PDF, PNG, JPG, WEBP
`VAL_2003`	400	Múltiplos arquivos PDF não permitidos	Envie um único PDF ou múltiplas imagens
`VAL_2004`	400	PDF e imagens não podem ser misturados	Envie PDF ou imagens, não ambos

Erros de Processamento (3000-3099)

Código	HTTP	Mensagem	Solução
`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 múltiplas requisições

Erros do Servidor (5000-5099)

Código	HTTP	Mensagem	Solução
`SRV_5001`	500	Erro interno do servidor	Tente novamente, entre em contato com o suporte se persistir
`SRV_5002`	503	Serviço temporariamente indisponível	Aguarde e tente novamente com backoff exponencial

Boas Práticas de Tratamento de Erros

Recomendações

Sempre verifique o campo status - Respostas de sucesso tem "status": "success"
Implemente lógica de retry para erros transitórios (5xx) com backoff exponencial
Registre códigos de erro para depuração e monitoramento
Exiba mensagens amigáveis baseadas nos códigos de erro