Erros

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