Backend Error Handling

Relevant source files

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

• marketplace-backend/app/src/filters/http-exception.filter.ts
• marketplace-backend/app/src/main.ts
• marketplace-backend/app/src/app.module.ts
• marketplace-backend/app/src/filters/index.ts
• marketplace-backend/app/package.json

Backend Error Handling manages how the application captures, processes, and returns errors to the client. The system uses a centralized exception filter to ensure all HTTP exceptions follow a consistent response format, preventing the leakage of sensitive internal stack traces while providing clear feedback to the consumer.

Global Filter Architecture

The application implements a global exception layer using the NestJS ExceptionFilter interface. This layer intercepts all unhandled HttpException instances across the entire backend.

HttpExceptionFilter Component

The HttpExceptionFilter class extracts the response object from the host execution context to send a custom JSON payload. It retrieves the HTTP status code from the exception and generates a timestamp for the error occurrence.

The diagram shows the interception of exceptions by the global filter before they reach the client.
Sources: marketplace-backend/app/src/filters/http-exception.filter.ts:1-24, marketplace-backend/app/src/main.ts:28

Global Registration

The filter is registered in two primary locations to ensure comprehensive coverage:

1. Main Entry Point: The bootstrap function applies the filter globally using app.useGlobalFilters().
2. App Module: The filter is provided using the APP_FILTER token within the AppModule providers array.

Sources: marketplace-backend/app/src/main.ts:28, marketplace-backend/app/src/app.module.ts:24-27

Data Structures and Flow

When an exception is caught, the system constructs a specific data structure. This structure ensures the frontend receives uniform error objects regardless of which module triggered the error.

Field	Type	Description
statusCode	Number	The HTTP status code (e.g., 404, 500).
timestamp	String	ISO string representing when the error occurred.
path	String	The URL path that triggered the exception.
message	String/Object	The error description provided by the exception.

Sources: marketplace-backend/app/src/filters/http-exception.filter.ts:16-21

Error Processing Sequence

The filter follows a strict sequence to resolve the error and respond to the client.

The sequence diagram illustrates how the filter handles the transition from a thrown exception to a structured JSON response.
Sources: marketplace-backend/app/src/filters/http-exception.filter.ts:12-23

Dependencies and Environment

The error handling system relies on core NestJS common libraries and environment configurations.

• @nestjs/common: Provides the Catch, ExceptionFilter, and HttpException decorators and classes.
• Execution Context: Uses ArgumentsHost to switch to the HTTP context for accessing Request and Response objects.
• Path Tracking: The filter uses request.url to identify the failing endpoint.

Sources: marketplace-backend/app/src/filters/http-exception.filter.ts:1-13, marketplace-backend/app/package.json:37

Implementation Detail

The implementation ensures that the HttpExceptionFilter is exported via a barrel file for clean imports throughout the application modules.

// marketplace-backend/app/src/filters/http-exception.filter.ts

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
    catch(exception: HttpException, host: ArgumentsHost): void {
        const ctx = host.switchToHttp();
        const response = ctx.getResponse<Response>();
        const request = ctx.getRequest<Request>();
        const status = exception.getStatus();

        response.status(status).json({
            statusCode: status,
            timestamp: new Date().toISOString(),
            path: request.url,
            message: exception.getResponse(),
        });
    }
}

Sources: marketplace-backend/app/src/filters/http-exception.filter.ts:7-24, marketplace-backend/app/src/filters/index.ts:1

Conclusion

The Backend Error Handling system provides a robust, centralized mechanism for managing failures. By utilizing a global HttpExceptionFilter, the project maintains a clean separation between business logic and error formatting, ensuring consistent API behavior across all modules including Auth and Customers.