error-handling

Centralized error handling standardizes how errors are created, logged, and reported across your codebase. Use AppError objects with defined ErrorCode values to categorize failures consistently, then normalize unknown exceptions through a common reporting layer. This ensures all errors follow the same structure, making debugging easier and user messaging consistent.

Catch exceptions in your route handlers or UI components, normalize them using normalizeError(), and convert to user messages with toUserMessage(). Include the errorId and errorCode in API responses so users can reference the error when contacting support. This separates internal debugging details from the experience your users see.

Return structured errors from endpoints by throwing AppError with a code, message, and context, then catching and reporting it. Include errorId, errorCode, and a user-friendly message in the JSON response. This gives clients consistent error data for UI handling and provides support teams with traceable error IDs for investigation.

Yes, error handling applies to both client and server environments. AppError, ErrorCode, and reporting utilities work across your full stack, enabling consistent error creation and propagation whether you're handling API failures, database errors, authentication issues, or UI-layer exceptions.

The recoverable flag indicates whether an error is transient and can be retried or permanent and requires user intervention. This flag helps client code decide whether to show a retry button, display a permanent failure message, or route to an error recovery workflow based on the error's nature.

AppError supports automatic errorId generation and integrated logging through reportError(), which captures the error code, message, context, and cause chain. This creates a traceable log entry tied to a unique errorId that users can provide to support, enabling quick correlation between user reports and backend logs.