Padrão de erros

Temos formatos padronizados de erros retornados pela API seguindo padrão de resposta HTTP, convencionais pra indiciar sucesso ou falha, seja por erro interno da aplicação ou erro na integração.

As respostas com um código de status chamadas de 4xx ou 5xx podem ser consideradas como falhas, enquanto respostas 2xx significam que sua solicitação foi processada com sucesso.

Em nossos endpoints os erros podem se diferenciar de acordo com cada necessidade por isso recomendamos que navegue nas páginas de erros e confira os possíveis retornos.

---

🚧

Qualidade na integração

Para que seja possível manter a integração com qualidade e fazer o melhor uso das funcionalidades oferecidas, é importante entender os possíveis erro e garantir que as validações sejam feitas antes do envio.

Confira abaixo os principais códigos de retorno que utilizamos:

Código	Status	Descrição
200 ou 201	OK	Sua solicitação foi concluída com sucesso, seja consulta (GET) ou envio (POST) de informação.
400	Bad Request	Indica que a solicitação não pôde ser concluída ou contém alguma informação incorreta/inválida. Verifique o detalhamento do erro no retorno
401	Invalid Token	Token de acesso utilizado está inválido ou expirado.
403	Forbidden	Você autenticou, mas não tem permissão para acessar o recurso.
404	Not found	Rota não foi encontrada ou existe alguma informação incorreta.
500	Internal Server Error	Ocorreu um erro interno na aplicação

Informações da resposta

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

Campo	Descrição
code	O código de status HTTP de erro retornado. Pode ser: 2xx, 4xx ou 5xx
key	Para erros de objeto de API, uma string curta da lista do lado direito, descrevendo o tipo de erro que ocorreu.
message	Uma mensagem legível que fornece uma breve descrição do erro.
details	Uma mensagem legível que fornece mais detalhes sobre o erro.

Os erros retornados seguem o formato JSON na seguinte estrutura:

Exemplo de Response

Error structure

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