Códigos de Resposta
Entenda todos os códigos de status HTTP e formatos de erro da API
Respostas de Sucesso (2xx)
Indicam que a requisição foi recebida, compreendida e processada com sucesso.
OK
A requisição foi processada com sucesso. O corpo da resposta contém os dados solicitados.
Created
Um novo recurso foi criado com sucesso. O corpo da resposta contém os dados do recurso criado.
No Content
A requisição foi processada com sucesso, mas não há conteúdo para retornar.
Erros do Cliente (4xx)
Indicam que houve um erro na requisição enviada pelo cliente.
Bad Request
A requisição está malformada ou contém parâmetros inválidos. Verifique a sintaxe e os dados enviados.
{
"error": {
"detail": "Documento deve ter exatamente 11 ou 14 dígitos",
"status_code": 400,
"title": "Bad Request",
"type": "https://httpstatuses.com/400"
}
}Unauthorized
A requisição requer autenticação. O token de acesso está ausente, inválido ou expirado.
Forbidden
O cliente está autenticado, mas não tem permissão para acessar o recurso solicitado.
Not Found
O recurso solicitado não foi encontrado no servidor. Verifique a URL e os parâmetros.
Unprocessable Entity
A requisição está bem formada, mas contém erros de validação nos dados de entrada.
Too Many Requests
O limite de requisições foi excedido. Aguarde antes de fazer novas requisições.
Erros do Servidor (5xx)
Indicam que houve um erro no servidor ao processar a requisição.
Internal Server Error
Erro interno do servidor. Entre em contato com o suporte se o problema persistir.
Service Unavailable
O serviço está temporariamente indisponível. Tente novamente mais tarde.
Formato Padrão de Erro
Todas as respostas de erro da API seguem um formato consistente para facilitar o tratamento pelos clientes:
Estrutura do Erro
| Campo | Tipo | Descrição |
|---|---|---|
error.status_code | string | Código único do erro para identificação programática |
error.title | string | Titulo, resumo do erro |
error.details | string | Os detalhes do erro ocorrido |
error.type | string | Link para mais informações sobre o erro |
Exemplo Completo
{
"error": {
"detail": "Documento deve ter exatamente 11 ou 14 dígitos",
"status_code": 400,
"title": "Bad Request",
"type": "https://httpstatuses.com/400"
}
}Boas Práticas para Tratamento de Erros
Sempre Verifique o Status
Sempre verifique o código de status HTTP antes de processar a resposta. Não assuma que a requisição foi bem-sucedida.
Trate Erros de Autenticação
Implemente lógica para renovar tokens automaticamente ou redirecionar para login quando receber erro 401.
Implemente Retry Logic
Para erros 5xx e 429, implemente lógica de retry com backoff exponencial respeitando o header Retry-After.
Log Request IDs
Sempre registre o request_id dos erros para facilitar o suporte e debugging. Isso acelera a resolução de problemas.