Errors vs Exceptions: Foundations of Robust Error Handling

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

/**
 * Function contract (implicit or explicit):
 * - Precondition: divisor !== 0
 * - Postcondition: result * divisor === dividend (within floating-point precision)
 * - Invariant: function is pure (no side effects)
 */
function divide(dividend: number, divisor: number): number {
    // Precondition violation → Error condition
    if (divisor === 0) {
        // This is an ERROR: the input violates the function's domain
        throw new Error("Division by zero: divisor must be non-zero");
    }
    
    // Normal execution path
    return dividend / divisor;
}
 
/**
 * The caller contracts:
 * - Caller promises: divisor !== 0
 * - Function promises: valid result
 * 
 * An error is a breach of this contract from either party.
 */

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

/**
 * A well-structured error contains all the information needed
 * for diagnosis, handling, and recovery.
 */
interface StructuredError {
    // Unique identifier for programmatic handling
    code: string;  // e.g., "USER_NOT_FOUND", "DATABASE_TIMEOUT"
    
    // Human-readable explanation
    message: string;
    
    // Severity level for triage
    severity: 'info' | 'warning' | 'error' | 'critical' | 'fatal';
    
    // When did this happen?
    timestamp: Date;
    
    // Where in the system?
    source: {
        component: string;  // e.g., "UserService"
        operation: string;  // e.g., "findById"
        layer: string;      // e.g., "service", "repository", "controller"
    };
    
    // What was the context?
    context: Record<string, unknown>;  // e.g., { userId: "abc123", attemptCount: 3 }
    
    // What caused this?
    cause?: Error | StructuredError;
    
    // How might we recover?
    recovery?: {
        isRetryable: boolean;
        suggestedAction?: string;
        retryAfterMs?: number;
    };
}
 
// Example instantiation
const error: StructuredError = {
    code: "DATABASE_CONNECTION_TIMEOUT",
    message: "Failed to connect to database within 5000ms",
    severity: "error",
    timestamp: new Date(),
    source: {
        component: "UserRepository",
        operation: "findUserById",
        layer: "repository"
    },
    context: {
        userId: "user_12345",
        databaseHost: "db-primary.example.com",
        timeoutMs: 5000,
        attemptNumber: 3
    },
    cause: new Error("ETIMEDOUT: Connection timed out"),
    recovery: {
        isRetryable: true,
        suggestedAction: "Retry with exponential backoff or use read replica",
        retryAfterMs: 1000
    }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

// FAULT: The underlying defect
// This function has a fault - it doesn't handle null input
function processUserData(data: UserData): ProcessedData {
    // FAULT: No null check exists here
    return {
        fullName: data.firstName + " " + data.lastName,  // Will fail if data is null
        email: data.email.toLowerCase()
    };
}
 
// ERROR: Incorrect system state when fault is activated
// When called with null, the system enters an erroneous state
try {
    const result = processUserData(null as any);  // FAULT ACTIVATED
    // ERROR: We're now in an incorrect state - result is undefined or
    // execution has been interrupted
} catch (e) {
    // ERROR is now manifested as an exception
    console.error("Error detected:", e);
}
 
// FAILURE: Observable deviation at system boundary
// If the error isn't caught and handled, it causes a failure
async function handleRequest(req: Request): Promise<Response> {
    const userData = await fetchUserData(req.userId);  // May return null
    const processed = processUserData(userData);       // ERROR if null
    
    // FAILURE: If error propagates, the HTTP request fails
    // User sees 500 error, transaction is rolled back, etc.
    return new Response(JSON.stringify(processed));
}
 
// DEFENSIVE DESIGN: Break the chain early
function processUserDataSafely(data: UserData | null): ProcessedData | null {
    // Break the chain at ERROR stage - detect the condition before it causes failure
    if (data === null) {
        // Error detected, prevented from becoming failure
        return null;  // Or throw a well-defined exception
    }
    
    return {
        fullName: data.firstName + " " + data.lastName,
        email: data.email.toLowerCase()
    };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

// IMMATURE: Error as exceptional interruption
// This design treats "not found" as an exception to normal flow
function getUserImmature(id: string): User {
    const user = database.query(`SELECT * FROM users WHERE id = ?`, id);
    if (!user) {
        throw new Error("User not found");  // Exception = something went wrong
    }
    return user;
}
 
// Usage forces try-catch everywhere
try {
    const user = getUserImmature("abc123");
    // ... do something with user
} catch (error) {
    // Is this "not found" or a database error? Hard to tell
    if (error.message === "User not found") {
        // Handle not found
    } else {
        // Handle other errors
    }
}
 
 
// MATURE: "Not found" is a valid outcome, not an exception
type UserResult = 
    | { success: true; user: User }
    | { success: false; error: 'NOT_FOUND' }
    | { success: false; error: 'DATABASE_ERROR'; details: string };
 
function getUserMature(id: string): UserResult {
    try {
        const user = database.query(`SELECT * FROM users WHERE id = ?`, id);
        
        if (!user) {
            // "Not found" is a valid, expected outcome
            return { success: false, error: 'NOT_FOUND' };
        }
        
        return { success: true, user };
        
    } catch (dbError) {
        // Database errors are actual problems
        return { 
            success: false, 
            error: 'DATABASE_ERROR', 
            details: dbError.message 
        };
    }
}
 
// Usage is explicit about all outcomes
const result = getUserMature("abc123");
 
switch (result.success) {
    case true:
        // Handle found user
        console.log(`Found: ${result.user.name}`);
        break;
        
    case false:
        switch (result.error) {
            case 'NOT_FOUND':
                // Handle expected "not found" case
                console.log("User does not exist");
                break;
            case 'DATABASE_ERROR':
                // Handle actual system problem
                console.error("Database problem:", result.details);
                break;
        }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

/**
 * A well-designed error provides different views for different audiences.
 */
interface MultiAudienceError {
    // For automated systems: structured, machine-readable
    machine: {
        code: string;           // "PAYMENT_INSUFFICIENT_FUNDS"
        category: string;       // "payment_error"
        isRetryable: boolean;
        retryAfterMs?: number;
    };
    
    // For end users: friendly, actionable
    user: {
        title: string;          // "Payment Declined"
        message: string;        // "Your card was declined. Please try a different payment method."
        actions: string[];      // ["Try another card", "Contact your bank"]
    };
    
    // For operators: context, impact, runbook
    operator: {
        severity: 'low' | 'medium' | 'high' | 'critical';
        affectedUsers: number;
        affectedSystems: string[];
        runbookUrl?: string;
    };
    
    // For developers: full technical details
    developer: {
        message: string;
        stackTrace: string;
        context: Record<string, unknown>;
        cause?: Error;
        timestamp: Date;
        requestId: string;
    };
}
 
// Example: Payment failure error
const paymentError: MultiAudienceError = {
    machine: {
        code: "PAYMENT_INSUFFICIENT_FUNDS",
        category: "payment_error",
        isRetryable: false,  // User needs to change payment method
    },
    user: {
        title: "Payment Declined",
        message: "Your card was declined due to insufficient funds. Please try a different payment method or contact your bank.",
        actions: ["Use a different card", "Try PayPal", "Contact support"]
    },
    operator: {
        severity: "low",  // Expected business error, not system problem
        affectedUsers: 1,
        affectedSystems: ["payment-service"],
    },
    developer: {
        message: "Payment processor returned decline code: insufficient_funds",
        stackTrace: "...",
        context: {
            userId: "user_123",
            orderId: "order_456",
            amount: 150.00,
            currency: "USD",
            paymentProcessor: "stripe",
            declineCode: "insufficient_funds"
        },
        timestamp: new Date(),
        requestId: "req_abc123"
    }
};