Merlin Backend 12 files · 0 subfolders
Copy to Workspace 08-ErrorHandling Shared from "Merlin Backend" on Inkdown
Error Handling Architecture
Overview
The error handling system provides robust resilience through typed errors, automatic retry logic, circuit breakers, and graceful degradation. It ensures system stability even when external services fail.
Error Hierarchy
02-DeepResearch.md
Typed Error Base Classes File: src/server/models/error/error.ts
Client Error (User-Facing)
Server Error (Internal)
Prompt Error (LLM Interaction)
Task Error (Background Jobs)
Error Types & Severity File: src/server/constantsSchemasAndTypes/global/globalConstants.ts
Retry Architecture File: src/server/utilities/retry.ts
Core Retry Function
Retry with Higher-Order Function
Parallel Execution with Settling All Settled (Don't Throw):
All Settled Throw on Error:
Circuit Breaker Pattern While not explicit circuit breakers, the system uses fail-fast patterns:
Search Provider Cascade
Scraping Tier Fallback
Orchestrator Error Handling File: src/server/endpoints/unified/orchestrator/toolOrchestrator.ts
Tool-Level Error Isolation
Invalid Tool Name Recovery
Deep Research Error Resilience File: src/server/endpoints/unified/features/deepResearch/deepResearch.ts
Step-Level Error Handling Pattern: Every major operation has try-catch. Log error, use fallback, continue execution.
Axios Error Handling File: src/server/services/axios.ts
Summary The error handling architecture:
Typed Errors : ClientError, ServerError, PromptError, TaskErrorSeverity Levels : INFO, WARNING, ERROR, CRITICALAutomatic Retry : retryAsyncFunction with contextProgressive Enhancement : Retry count drives behavior changesSettle Patterns : settleAll (continue), settleAllOrThrow (fail)Circuit Breakers : Provider cascades, tier fallbacksTool Isolation : One tool error doesn't crash orchestratorDeep Research Resilience : Every step wrapped in try-catchGraceful Degradation : Empty results instead of crashesSecurity : Remove sensitive data from error objects Key Principle: Fail gracefully, never crash the conversation. Log everything, alert on patterns, degrade service rather than deny it.
