Error Handling & Observability

Relevant source files

The following files were used as context for generating this wiki page:

• backend/src/shared/errors/AppError.ts
• backend/src/interfaces/http/middleware/errorHandler.middleware.ts
• backend/src/shared/errors/HttpError.ts
• backend/src/app.ts
• infrastructure/aws/cdk/lib/atlasclean-stack.ts
• backend/src/config/index.ts

Error Handling and Observability in AtlasCleanAI Enterprise provides a standardized mechanism for identifying, capturing, and reporting application failures while monitoring the health and performance of the platform. The system uses a centralized error handling middleware to process operational errors and leverages AWS-native services for infrastructure-level observability.

This module ensures that both the API consumers receive consistent error responses and the operations team gains visibility into system behavior through logs, health checks, and container insights.
Sources: README.md, backend/src/app.ts:208-210

Centralized Error Handling Architecture

The backend utilizes a custom AppError class as the foundation for all operational errors. The architecture separates "operational" errors (predicted failures like validation or authentication issues) from "unhandled" errors (unexpected code failures).

Custom Error Hierarchy

All specialized HTTP errors extend from a base HttpError, which in turn extends AppError. This hierarchy allows the system to attach HTTP status codes and machine-readable error codes to exceptions thrown within use cases or controllers.

The diagram shows the inheritance structure of the application's error classes.
Sources: backend/src/shared/errors/AppError.ts:1-15, backend/src/shared/errors/HttpError.ts:1-38

Standard Error Classes

Class	HTTP Status	Code	Usage
ValidationError	400	VALIDATION_ERROR	Thrown when Zod schema validation fails.
UnauthorizedError	401	UNAUTHORIZED	Thrown when JWT or API key is missing/invalid.
ForbiddenError	403	FORBIDDEN	Thrown when user lacks sufficient permissions.
NotFoundError	404	NOT_FOUND	Thrown when a resource or route does not exist.
ConflictError	409	CONFLICT	Thrown for resource state violations.

Sources: backend/src/shared/errors/HttpError.ts:9-38, backend/src/app.ts:200-207

Global Request Processing Flow

The system processes errors through an Express middleware positioned after all route definitions. If a component throws an AppError, the middleware extracts the status code and details to return a JSON response. For all other errors, it logs the stack trace and returns a generic 500 INTERNAL_SERVER_ERROR.

The flow shows how the errorHandler middleware differentiates between known operational errors and unexpected crashes.
Sources: backend/src/interfaces/http/middleware/errorHandler.middleware.ts:6-34

Infrastructure Observability

In production environments, the platform transitions from local console logging to a managed AWS observability stack.

CloudWatch Monitoring

The AtlasCleanStack configures specialized logging and monitoring for the containerized services:

• Log Groups: A dedicated LogGroup handles logs from the ECS Backend Container with a 30-day retention policy.
• Container Insights: Enabled on the ECS Cluster to track CPU and memory metrics per task.
• Health Checks: The Application Load Balancer (ALB) and ECS service perform active health checks against the /health endpoint.

Sources: infrastructure/aws/cdk/lib/atlasclean-stack.ts:74-78, infrastructure/aws/cdk/lib/atlasclean-stack.ts:255-260

Health Monitoring Endpoint

The /health endpoint serves as the primary heartbeat for monitoring. It returns the current status, system uptime, and a timestamp.

app.get('/health', (_request, response) => {
  response.status(200).json({
    success: true,
    data: {
      status: 'ok',
      uptime: process.uptime(),
      timestamp: new Date().toISOString(),
    },
  });
});

Sources: backend/src/app.ts:182-192

Logging and Secrets Management

The platform utilizes a structured logger (Winston) for application-level events. The log level is configurable via the LOG_LEVEL environment variable, defaulting to info. For security, infrastructure-level secrets (like database credentials and JWT keys) are stored in AWS Secrets Manager and provided to the application as environment variables or direct secret refs, preventing exposure in logs.

Sources: backend/src/config/index.ts:61, infrastructure/aws/cdk/lib/atlasclean-stack.ts:223-228

Summary

Error Handling & Observability in AtlasCleanAI Enterprise enforces consistency through a structured error hierarchy and centralized middleware. By distinguishing operational errors from system failures, it maintains security and developer productivity. Cloud-native integration with AWS CloudWatch and ELB health checks ensures high availability and rapid incident response in production environments.