Tratamento de Erros

Nossa API usa códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição. Quando uma chamada falha, nós sempre retornamos um corpo JSON padronizado que fornece detalhes sobre o que deu errado.

A melhor prática para sua integração é:

• Verificar o código de status HTTP (o "o quê").
• Analisar (parse) o corpo da resposta JSON (o "porquê").
• Implementar sua lógica de retry (nova tentativa) ou de tratamento com base no error_code que fornecemos.

🚧

Atenção aos Erros Específicos: Os códigos e mensagens de erro podem variar conforme o endpoint. Consulte sempre a seção de respostas de cada recurso para tratar as exceções corretamente.

1. Estrutura da Resposta de um Erro

Qualquer chamada que não resulte em um 2xx (Sucesso) retornará um objeto JSON com a seguinte estrutura. Nós nunca retornamos uma string HTML ou um erro genérico.

Exemplo de Resposta de Erro (ex: 400 Bad Request)

{
    "code": "REQUEST_VALIDATION_ERROR",
    "message": "Some fields are not valid",
    "details": [
        {
            "target": "field",
            "message": "error description"
        }
    ]
}

1.1. Campos do Objeto de Erro

Mantemos um modelo de retorno onde buscamos fornecer informações para que seja possível entender o erro de acordo com cada endpoint e suas especificidades. Veja abaixo os campos retornados:

2. Códigos de Status HTTP