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

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