Envelope e erros

Toda resposta vem embrulhada

Nenhuma rota devolve o recurso na raiz do corpo. O recurso vem sempre em data:

{
  "code": 200,
  "message": "OK",
  "timestamp": 1758585600000,
  "data": { }
}

Em respostas paginadas há também meta. Ao escrever seu cliente, leia response.data.data — não response.data.

O code repete o status HTTP da resposta, mas só no envelope de sucesso. O schema publicado em /openapi/v1.json não declara esse campo nas respostas — só data, message e timestamp — então um cliente gerado direto do spec pode sair sem code no tipo, e é preciso adicioná-lo à mão.

Respostas de erro usam um envelope diferente, sem code nenhum — ver a seção seguinte. Um cliente que leia err.response.data.code esperando o status recebe undefined em todo caminho de erro, a mesma armadilha já citada acima para response.data.

Erro de validação

Campo inválido ou ausente responde 400 com uma entrada por campo, e as mensagens vêm em português. O envelope de erro não é o mesmo de sucesso: o status HTTP vem em status, não em code, e cada item de errors carrega também o valor rejeitado em value:

{
  "success": false,
  "status": 400,
  "message": "Validation error",
  "errors": [
    {
      "property": "ownerData",
      "message": ["Deve ser um objeto"],
      "value": null
    }
  ],
  "context": null,
  "extraData": {}
}

O property usa caminho com ponto para campo aninhado (ownerData.cpf) e colchete para item de lista (rules[0].inputName). context e extraData normalmente vêm vazios (null / {}); quando a rota anexa contexto extra ao erro, ele aparece ali.

Erro de regra de negócio

Vem com o status HTTP correspondente e uma mensagem em português, por exemplo 400 com "Tipo de documento não suportado".

Códigos

código	quando acontece
400	campo inválido, ou regra de negócio recusou a requisição
401	x-api-key ausente, malformada, revogada ou inválida
403	recurso não disponível para a sua chave; em chave escopada, também rota sem a permissão necessária ou recurso fora dos projetos da chave
404	o recurso não existe