Error Handling

Last Updated: May 20, 2025

This document provides an overview of the error handling architecture in the Typus Development Framework.

Overview

The error handling system provides robust mechanisms for catching, processing, logging, and responding to errors throughout the application. It ensures consistent error responses, proper logging, and helps maintain application stability.

Error Handling Flow Diagram

Error Types Hierarchy

Backend BaseError

The foundation class for all backend application-specific errors. Provides standardized error properties:

• Properties:
  • message: Human-readable error description
  • code: Machine-readable error identifier
  • status: HTTP status code for API responses
  • context: Additional error context
  • name: Error class name
• Methods:
  • toJSON(): Serializes the error for API responses

Backend Specialized Error Types

Derived from BaseError to handle specific scenarios:

• NotFoundError: Resource not found cases (404)
• BadRequestError: Invalid request format or parameters (400)
• UnauthorizedError: Authentication issues (401)
• ForbiddenError: Permission/access problems (403)
• ValidationError: Input validation failures with detailed errors array (400)

Frontend AppError

The foundation class for frontend application-specific errors:

• Properties:
  • message: Human-readable error description
  • code: Machine-readable error identifier
  • data: Additional error data

Error Handling Systems

Backend Error Handling Middleware

Central component that catches unhandled errors and processes them:

• Functionality:
  • Catches errors thrown from route handlers
  • Normalizes errors to a consistent format
  • Determines appropriate HTTP status codes
  • Structures error responses
  • Integrates with the logging system
  • Hides sensitive error details in production

Frontend Error Handler

Centralized error handling system for the frontend:

• Functionality:
  • Error classification and context extraction
  • Display mode determination based on severity and error code
  • Recovery actions management
  • Error cycle prevention to avoid infinite loops
  • Integration with logging system
  • UI notification via event bus

Error Response Structure

Standardized format for communicating errors to clients:

• Format:
  • success: Boolean flag (false for errors)
  • error: Error information object
    • code: Machine-readable error identifier
    • message: User-friendly error description
    • details: Additional context (when appropriate)

Error Handling Across Layers

Controller Layer

Error handling integrated into the controller layer:

• Try/Catch Patterns: Structured error catching in controller methods
• Error Transformation: Conversion of system errors to application errors
• Contextual Enhancement: Adding request context to error information

Service Layer

Error handling strategies for the business logic layer:

• Domain-Specific Errors: Custom errors for business rule violations
• Error Propagation: Proper error bubbling to calling layers
• Error Enrichment: Adding service context to errors

Database Layer

Strategies for managing database-related errors:

• Query Error Processing: Converting database errors to application errors
• Transaction Management: Proper error handling during transactions
• Connection Error Recovery: Strategies for handling connection failures

Asynchronous Error Handling

Special considerations for asynchronous operations:

• Promise Error Chains: Structured .catch() handlers
• Async/Await Patterns: Try/catch blocks for async functions
• Unhandled Rejection Tracking: Global handlers for missed promise errors

Frontend Error Handling

The frontend implements a comprehensive error handling system:

Error UI Manager

A global error UI manager that:

• Subscribes to the error event bus
• Routes errors to appropriate UI components based on display mode
• Handles session clearing for authentication errors

Error Display Modes

Multiple ways to display errors to users:

• Modal: For important errors that require user attention
• Toast: For non-critical notifications
• Fullscreen: For critical system errors (dedicated error page)
• None: For silent errors that are only logged

Recovery Actions

Predefined recovery strategies that can be triggered by users:

• reloadPage: Refreshes the current page
• resetTheme: Resets theme settings and reloads
• clearSession: Clears user session and authentication data
• logOnly: Just logs the error without UI action

Error System Component

A dedicated Vue component that:

• Displays full-screen error information
• Shows error details when appropriate
• Provides recovery action buttons
• Uses theme-consistent styling

Integration with Logging System

Comprehensive error logging strategy:

• Error Detail Capture: Full error details recorded
• Stack Trace Preservation: Complete stack information retained
• Context Enrichment: Adding environment and request information
• Sensitive Data Filtering: Removing sensitive information from logs

Error Monitoring and Alerting

Approaches for monitoring and responding to errors:

• Error Rate Monitoring: Tracking error frequency and patterns
• Critical Error Alerting: Notification system for severe errors
• Error Analytics: Analyzing error trends and common issues
• Health Checks: Proactive monitoring to detect potential issues

Conclusion

The error handling architecture ensures consistent management of errors across all application layers, providing clear information to users while maintaining detailed diagnostics for developers. This comprehensive approach helps maintain application stability and provides a better user experience when issues occur.