Error Contracts and HTTP Error Responses

This document defines how errors are represented in code and serialized through HTTP adapters.

1) Base Error Contract

All domain/infra errors extend BaseError (apps/backend-template/src/infra/exceptions/BaseError.ts) and expose:

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

2) Canonical Error Codes

Defined in apps/backend-template/src/infra/exceptions/error.codes.ts:

Status mapping is resolved by toHttpStatus(...) in apps/backend-template/src/shared/utils.ts.

3) Error Class to Code Mapping

4) HTTP Error Response Shape

Current adapters serialize to the same payload shape:

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

Sources:

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

5) MessageMediator Request/Response Error Contract

For contract-based inter-service calls:

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

Errors are carried in the same response envelope (no throw required at transport boundary).

6) Current Consistency Notes

1. Error status mapping is centralized (toHttpStatus).
2. Human-readable formatting is centralized (formatErrorMessage).
3. Correlation id is captured in BaseError from request context.
4. New adapters should reuse existing sendErrorResponse semantics to preserve response contract consistency.

7) HTTP Request Validation Contract

All HTTP adapters use the same OpenAPI request-validation boundary:

1. Unknown properties and required properties are checked first so existing public error messages remain stable.
2. OpenAPI type, format, enum, range, and length constraints are then enforced.
3. Schema-library diagnostics are translated when a stable domain-facing message already exists.
4. createdAt and updatedAt are tolerated in update round trips as server-managed fields; they are not writable domain attributes.

Changes to request schemas or validation messages must be covered by the shared validator unit tests and the affected adapter integration suites.

8) Extension Rules

When creating a new custom error:

1. Extend BaseError.
2. Assign a stable name and code.
3. Ensure code is covered in EErrorStringCodes/EErrorNumberCodes.
4. Add formatErrorMessage branch if custom human-readable text is required.
5. Keep HTTP and message-level error envelopes backward-compatible.

9) Realtime Error Envelopes

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"
}

See transport-specific contract references:

• documentation/md/contracts/WEBSOCKET-REALTIME-CONTRACTS.md
• documentation/md/contracts/GRPC-REALTIME-CONTRACTS.md