Contratos de erro e respostas de erro HTTP

Este documento define como os erros são representados no código e serializados por meio de adaptadores HTTP.

1) Contrato de erro básico

Todos os erros de domínio/infra estendem BaseError (apps/backend-template/src/infra/exceptions/BaseError.ts) e expõem:

{
  name: string;
  code: string; // EErrorStringCodes
  message: string;
  correlationId: string;
  cause?: Error;
  metadata?: unknown;
}

2) Códigos de erro canônicos

Definido em apps/backend-template/src/infra/exceptions/error.codes.ts:

O mapeamento de status é resolvido por toHttpStatus(...) em apps/backend-template/src/shared/utils.ts.

3) Classe de erro para mapeamento de código

4) Formato de resposta de erro HTTP

Os adaptadores atuais são serializados no mesmo formato de carga útil:

{
  "message": "Human readable message",
  "error": {
    "name": "error_name",
    "code": "GENERIC.SOME_CODE",
    "message": "Original message",
    "correlationId": "..."
  }
}

Fontes:

• Express/Fastify/Restify: sendErrorResponse(...)
• Adaptadores Lambda: apps/backend-template/src/interface/HTTP/adapters/aws/lambda/responses/sendErrorResponse.ts

5) Contrato de erro de solicitação/resposta do MessageMediator

Para chamadas interserviços baseadas em contrato:

interface IMessageResponse<TResult = any> {
  contract: string;
  result?: TResult;
  error?: Error | Record<string, any>;
}

Os erros são transportados no mesmo envelope de resposta (não é necessário lançar no limite de transporte).

6) Notas de Consistência Atual

1. O mapeamento de status de erro é centralizado (toHttpStatus).
2. A formatação legível é centralizada (formatErrorMessage).
3. O ID de correlação é capturado em BaseError do contexto da solicitação.
4. Novos adaptadores devem reutilizar a semântica sendErrorResponse existente para preservar a consistência do contrato de resposta.

7) Contrato de validação de requisições HTTP

Todos os adaptadores HTTP usam o mesmo limite de validação de requisições OpenAPI:

1. Propriedades desconhecidas e obrigatórias são verificadas primeiro para manter estáveis as mensagens públicas existentes.
2. Em seguida, são aplicadas as restrições OpenAPI de tipo, formato, enumeração, intervalo e tamanho.
3. Diagnósticos da biblioteca de schema são traduzidos quando já existe uma mensagem estável voltada ao domínio.
4. createdAt e updatedAt são tolerados em ciclos de leitura e atualização como campos gerenciados pelo servidor; eles não são atributos de domínio graváveis.

Alterações nos schemas de requisição ou nas mensagens de validação devem ser cobertas pelos testes unitários compartilhados do validador e pelas suítes de integração dos adaptadores afetados.

8) Regras de extensão

Ao criar um novo erro personalizado:

1. Estenda BaseError.
2. Atribua um nome e um código estáveis.
3. Certifique-se de que o código esteja coberto em EErrorStringCodes/EErrorNumberCodes.
4. Adicione a ramificação formatErrorMessage se for necessário um texto legível personalizado.
5. Mantenha os envelopes de erro HTTP e de mensagem compatíveis com versões anteriores.

9) Envelopes de erro em tempo real

WebSocket (ApiResponse):

{
  "ok": false,
  "operationId": "createOrganization",
  "error": {
    "name": "validation_error",
    "message": "Invalid input data"
  }
}

gRPC (AsyncApiResponse):

{
  "ok": false,
  "operationId": "createOrganization",
  "errorName": "validation_error",
  "errorMessage": "Invalid input data"
}

Veja referências contratuais específicas de transporte:

• documentation/md/contracts/WEBSOCKET-REALTIME-CONTRACTS.md
• documentação/md/contratos/GRPC-REALTIME-CONTRACTS.md