Tratamento de Erros

A Perpetuus API utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição de API. Em caso de erro, a API retorna um payload JSON estruturado contendo detalhes sobre o problema para facilitar o diagnóstico.

Estrutura do Erro JSON

Todos os erros retornados pela API seguem este formato de envelope:

{
  "error": {
    "status": 400,
    "name": "ValidationError",
    "message": "x-tenant-id header is required",
    "details": {}
  }
}

• status: O código de status HTTP correspondente.
• name: A classe ou categoria do erro (ex: ValidationError, UnauthorizedError, ForbiddenError, NotFoundError).
• message: Uma descrição clara do erro legível por humanos.
• details: Detalhes adicionais específicos (como validação de campos ausentes ou chaves duplicadas).

Tabela de Códigos de Status HTTP

Exemplo de Erro de Validação (400)

Ao tentar criar um card sem preencher os campos dinâmicos obrigatórios definidos para a fase de entrada (Phase 0):

{
  "error": {
    "status": 400,
    "name": "ValidationError",
    "message": "Fields validation failed",
    "details": {
      "errors": [
        {
          "path": ["name"],
          "message": "O campo 'name' é obrigatório no formulário de entrada deste Board."
        }
      ]
    }
  }
}