Skip to main content
The Error Handling Utilities module serves as a critical component in Sophra’s robust error management infrastructure. This sophisticated utility set enhances the system’s ability to capture, process, and report errors across the entire microservices architecture. By providing a standardized approach to error handling, it significantly improves debugging efficiency, system reliability, and overall operational transparency. At its core, the module introduces a CustomError class, which extends JavaScript’s native Error object. This extension allows for more granular error categorization through error codes, facilitating easier error identification and resolution. The CustomError class also maintains the original error stack trace, crucial for pinpointing the exact location of issues in Sophra’s complex, distributed environment. The architectural decision to implement a custom error handling system reflects Sophra’s commitment to maintainability and scalability. By centralizing error management, the system can more effectively track and respond to issues across its various services, from the authentication layer to the search and analytics engines. This approach significantly reduces the cognitive load on developers when dealing with errors and streamlines the process of system-wide error analysis. Performance-wise, the Error Handling Utilities are designed to have minimal impact on system resources. The CustomError class and formatError function are lightweight, focusing on efficient data structuring rather than heavy processing. This design choice ensures that error handling doesn’t become a bottleneck, even in high-throughput scenarios typical in Sophra’s data-intensive operations. A unique feature of this module is its JSON serialization capability. The toJSON method of the CustomError class allows for seamless integration with logging systems and external monitoring tools. This feature is particularly valuable in Sophra’s context, where error data often needs to be transmitted between services or stored for later analysis. The structured JSON output facilitates easy parsing and aggregation of error data, enhancing Sophra’s ability to perform system-wide health assessments and trend analyses.

​
Exported Components

export class CustomError extends Error {
  readonly code: string;
  readonly originalError?: Error;

  constructor(code: string, originalError?: Error);
  toJSON(): Record<string, unknown>;
}

​
CustomError

The CustomError class extends the native Error class with additional functionality:
  • code: A string identifier for the error type
  • originalError: An optional field to store the original error that caused this custom error
  • constructor(code: string, originalError?: Error): Creates a new CustomError instance
  • toJSON(): Converts the error to a JSON-serializable object

​
formatError

The formatError function takes an Error object and returns a formatted string representation:
  • Input: error: Error
  • Output: string (JSON-formatted error details)

​
Implementation Examples

import { CustomError } from '@sophra/lib/cortex/utils/errors';

try {
  // Some operation that might fail
  throw new Error('Database connection failed');
} catch (err) {
  throw new CustomError('DB_CONNECTION_ERROR', err as Error);
}

​
Sophra Integration Details

The Error Handling Utilities integrate seamlessly with Sophra’s microservices architecture:
  1. API Gateway: Utilizes CustomError for standardized error responses across all endpoints.
  2. Authentication Service: Employs custom error codes for various authentication failures.
  3. Search Service: Uses formatError to log structured error data for failed search operations.
  4. Analytics Engine: Incorporates error data into its metrics for system health monitoring.
Error Flow in Sophra System

​
Error Handling

The Error Handling Utilities provide comprehensive coverage for various error scenarios:
  • Custom error codes: NETWORK_TIMEOUT, CONNECTION_REFUSED
  • Recovery: Implement retry logic with exponential backoff
  • Logging: Use formatError to capture full error context
  • Custom error codes: INVALID_INPUT, SCHEMA_VIOLATION
  • Recovery: Return detailed error messages to the client for correction
  • Monitoring: Aggregate validation errors to identify common issues
  • Custom error codes: INVALID_TOKEN, EXPIRED_SESSION
  • Recovery: Prompt user re-authentication
  • Security: Log authentication failures for potential breach detection

​
Data Flow

​
Performance Considerations

The Error Handling Utilities are designed for minimal performance impact:
  • CustomError creation: O(1) time complexity
  • formatError: O(n) where n is the size of the error stack
  • Memory usage: Negligible increase over standard Error objects
Benchmark: Error creation and formatting operations typically complete in under 0.1ms on standard hardware.

​
Security Implementation

The Error Handling Utilities contribute to Sophra’s security model:
  • Sanitization: formatError ensures sensitive data is not exposed in error messages
  • Audit Trail: All CustomError instances are logged for security analysis
  • Rate Limiting: Error rates are monitored to detect potential attacks

Security Best Practice

Always use CustomError with specific error codes to ensure consistent error handling and avoid information leakage.

​
Configuration

The Error Handling Utilities can be configured through environment variables: 
ERROR_STACK_TRACE_LIMIT=10
ERROR_LOGGING_LEVEL=INFO
ERROR_REPORTING_SERVICE=DATADOG
Runtime options can be set to customize error behavior: 
import { setErrorOptions } from '@sophra/lib/cortex/utils/errors';

setErrorOptions({
  includeOriginalError: process.env.NODE_ENV !== 'production',
  maxStackTraceLines: 20,
});
By leveraging these Error Handling Utilities, Sophra ensures a robust, secure, and performant error management system across its entire architecture.