Nos retornos de erros de requisição do cliente (status 4XX), as APIs vão retornar erros em um formato pré-definido, descrito abaixo:
{
"errors": [
{
"field": "NOME_DO_CAMPO",
"type": "TIPO_DO_ERRO",
"msg": "DESCRIÇÂO_DO_ERRO"
},
{
"field": "NOME_DO_CAMPO_2",
"type": "TIPO_DO_ERRO",
"msg": "DESCRIÇÂO_DO_ERRO"
}
]
}
Onde é descrito os erros de cada campo da requisição, permitindo identificar em que parte da requisição ocorreu um ou mais erros. Por exemplo, em uma requisição de criação de um item, que é enviado o seguinte corpo de mensagem:
{
"name": "item01",
"description": "Item 01 ABC",
"data": {
"value": 1
},
"data_list": [
{"value": "valid"}
{"value": "invalid"}
]
}
Pode ser retornado a seguinte resposta:
{
"errors": [
{
"type": "duplicated",
"field": "name",
"msg": "Já existe um item com o nome 'item01'"
},
{
"type": "invalid",
"field": "data.value",
"msg": "O valor '1' é menor que o valor mínimo permitido, min: 15"
},
{
"type": "invalid",
"field": "data_list[1].value",
"msg": "O valor do campo não é válido"
}
]
}
Juntamente com o status HTTP retornado pela API, o corpo da resposta
da API pode ser utilizado para identificar os erros que ocorreram.
Nesta resposta de API acima, por exemplo, pode ser visualizado que
já existe um item com o mesmo valor do campo name e que o campo
data.value está abaixo do mínimo permitido.
Os possíveis tipos de erros estão descritos abaixo:
| tipo | descrição |
|---|---|
| duplicated | Campo duplicado, já existe um item com o mesmo valor |
| invalid | Valor do campo não está de acordo com os padrões definidos pela API |
| required | Campo obrigatório não enviado dentro do json da requisição |
| not_found | Em campos de relacionamento de recursos, foi enviado o id de um item que não existe |