@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-05-calling-patterns.md

@@ -1,671 +1,671 @@
-# Module 5: Calling Patterns
-
-**Level:** Intermediate
-**Estimated Time:** 30 minutes
-
-## Overview
-
-This module provides practical code patterns for handling errors in your Fluent Commerce integrations, from basic try-catch blocks to comprehensive error handling with monitoring.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Write basic error handling code with try-catch
-- ✅ Implement comprehensive error handling for production systems
-- ✅ Add error monitoring and metrics collection
-- ✅ Know when to retry vs when to fail immediately
-
-## Basic Error Handling
-
-### Logging Setup
-
-**First, set up logging based on your runtime:**
-
-```typescript
-// Standalone (Node.js/Deno)
-import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'OrderProcessing' });
-
-// Versori Platform
-const { log: logger } = ctx;  // Use native platform log
-```
-
-### Minimal Pattern
-
-The simplest error handling pattern - catch and log:
-
-```typescript
-import {
-  XMLParserService,
-  GraphQLMutationMapper,
-  FluentClient,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Standalone
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'OrderProcessing' });
-
-// Versori Platform
-// const { log: logger } = ctx;
-
-async function processOrder(xmlContent: string) {
-  try {
-    // Parse XML
-    const parser = new XMLParserService();
-    const parsed = await parser.parse(xmlContent);
-
-    // Map to GraphQL mutation
-    const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-    const payload = await mapper.map(parsed);
-
-    // Execute mutation
-    // Throws GraphQLExecutionError on failure
-    const result = await client.graphql(payload);
-
-    return result.data;
-
-  } catch (error) {
-    logger.error('Order processing failed', error);
-    throw error;  // Re-throw for upstream handling
-  }
-}
-```
-
-**Key points:**
-- ✅ Wraps all operations in try-catch
-- ✅ Logs the error
-- ✅ Re-throws error (doesn't silence failures)
-- ❌ No specific error type handling
-- ❌ No retry logic
-
-### Intermediate Pattern with Type Checking
-
-Add specific handling for different error types:
-
-```typescript
-import {
-  XMLParserService,
-  GraphQLMutationMapper,
-  FluentClient,
-  FileParsingError,
-  PathResolutionError,
-  MappingError,
-  IngestionError,
-  GraphQLExecutionError
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processOrder(xmlContent: string) {
-  try {
-    // Parse XML
-    const parser = new XMLParserService();
-    const parsed = await parser.parse(xmlContent);
-
-    // Map to GraphQL mutation
-    const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-    const payload = await mapper.map(parsed);
-
-    // Execute mutation (only if no errors above)
-    // Throws GraphQLExecutionError on failure
-    const result = await client.graphql(payload);
-
-    return result.data;  // ✅ Complete data or nothing
-
-  } catch (error) {
-    // ✅ IMPORTANT: No partial data - mutation never executed or was rejected
-
-    if (error instanceof GraphQLExecutionError) {
-      // GraphQL errors from Fluent
-      logger.error('GraphQL error:', {
-        message: error.message,
-        errors: error.getErrorMessages(),
-        query: error.query
-      });
-      
-      // Classify errors to determine retry strategy
-      if (error.isAuthError()) {
-        // Auth error
-      } else if (error.isValidationError()) {
-        // Validation error
-      }
-      
-      throw error;
-    } else if (error instanceof FileParsingError) {
-      // XML parsing failed
-      logger.error('Invalid XML file:', {
-        code: error.code,
-        fileName: error.fileName,
-        lineNumber: error.lineNumber,
-        message: error.message
-      });
-      // Alert user: File is corrupt or invalid format
-      throw error;  // Don't retry
-
-    } else if (error instanceof PathResolutionError) {
-      // Wrong path in mapping config
-      logger.error('Path resolution failed:', {
-        path: error.path,
-        message: error.message
-      });
-      // Alert developer: Fix mapping configuration
-      throw error;  // Don't retry
-
-    } else if (error instanceof MappingError) {
-      // Required field missing or type mismatch
-      logger.error('Mapping failed:', {
-        field: error.field,
-        sourcePath: error.sourcePath,
-        message: error.message
-      });
-      // Alert developer: Data doesn't match mapping expectations
-      throw error;  // Don't retry
-
-    } else if (error instanceof IngestionError) {
-      logger.error('Ingestion error:', error.toJSON());
-
-      // Retry if transient error
-      if (error.isRetryable()) {
-        return scheduleRetry();
-      }
-      throw error;  // Non-retryable
-    }
-
-    // Unknown error
-    throw error;
-  }
-}
-```
-
-**Key points:**
-- ✅ Checks specific error types with `instanceof`
-- ✅ Logs error-specific context
-- ✅ Uses `error.isRetryable()` for retry decisions
-- ✅ Different handling for different error types
-- ✅ Clear comments explaining each case
-
-## Comprehensive Error Handling
-
-### Production-Ready Pattern with Retry Logic
-
-Complete error handling for production systems:
-
-```typescript
-import {
-  createClient,
-  XMLParserService,
-  GraphQLMutationMapper,
-  FileParsingError,
-  PathResolutionError,
-  MappingError,
-  ValidationError,
-  IngestionError,
-  IngestionErrorCode,
-  GraphQLExecutionError,
-  FluentAPIError
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processOrderWithRetry(
-  xmlContent: string,
-  maxRetries = 3
-): Promise<any> {
-  let attempt = 0;
-
-  while (attempt < maxRetries) {
-    try {
-      attempt++;
-
-      // Parse XML
-      const parser = new XMLParserService();
-      let parsed;
-
-      try {
-        parsed = await parser.parse(xmlContent);
-      } catch (error) {
-        if (error instanceof FileParsingError) {
-          // Parse error = permanent failure, don't retry
-          logger.error('XML parse error (permanent):', {
-            code: error.code,
-            fileName: error.fileName,
-            message: error.message
-          });
-          throw error;  // Don't retry
-        }
-        throw error;
-      }
-
-      // Map to mutation
-      const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-      let payload;
-
-      try {
-        payload = await mapper.map(parsed);
-      } catch (error) {
-        if (error instanceof PathResolutionError) {
-          // Wrong path = permanent failure (config issue)
-          logger.error('Path error (permanent):', {
-            path: error.path,
-            message: error.message
-          });
-          throw error;  // Don't retry
-
-        } else if (error instanceof MappingError) {
-          // Mapping error = permanent failure (data/config issue)
-          logger.error('Mapping error (permanent):', {
-            field: error.field,
-            sourcePath: error.sourcePath,
-            message: error.message
-          });
-          throw error;  // Don't retry
-        }
-        throw error;
-      }
-
-      // Execute mutation
-      const result = await client.graphql(payload);
-
-      // Success - return complete data
-      return result.data;
-
-    } catch (error) {
-      // Check if error is retryable
-
-      // 1. GraphQL Execution Error (e.g. Timeout/Network in GraphQL response)
-      if (error instanceof GraphQLExecutionError) {
-         const graphqlError = error.graphqlErrors[0];
-         
-         if (graphqlError.extensions?.code === 'TIMEOUT' || 
-             graphqlError.extensions?.code === 'NETWORK_ERROR') {
-            
-            if (attempt < maxRetries) {
-              await delay(1000 * attempt);
-              continue;  // Retry
-            }
-         }
-         // Permanent GraphQL error
-         throw error;
-      }
-      
-      // 2. Ingestion Error (Network, etc.)
-      if (error instanceof IngestionError && error.isRetryable()) {
-        if (attempt < maxRetries) {
-          logger.warn(`Retryable error, attempt ${attempt}/${maxRetries}`, {
-            code: error.code,
-            message: error.message
-          });
-
-          // Exponential backoff
-          await delay(1000 * Math.pow(2, attempt - 1));
-          continue;
-        }
-      }
-      
-      // 3. Fluent API Error (HTTP 5xx)
-      if (error instanceof FluentAPIError && error.statusCode >= 500) {
-         if (attempt < maxRetries) {
-            await delay(1000 * attempt);
-            continue;
-         }
-      }
-
-      // Non-retryable error or max retries exceeded
-      logger.error('Order processing failed:', {
-        attempt,
-        error: error instanceof IngestionError ? error.toJSON() : error.message
-      });
-
-      throw error;
-    }
-  }
-
-  throw new Error('Max retries exceeded');
-}
-
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-```
-
-**Key points:**
-- ✅ Retry loop with max attempts
-- ✅ Specific handling at each stage (parse, map, execute)
-- ✅ Permanent errors immediately thrown (no retry)
-- ✅ Transient errors retried with exponential backoff
-- ✅ GraphQL errors classified by code
-- ✅ Detailed logging at each stage
-
-## Error Handling with Monitoring
-
-### Adding Metrics Collection
-
-Track error patterns for alerting and analysis:
-
-```typescript
-import {
-  IngestionError,
-  IngestionErrorCode,
-  MappingError,
-  PathResolutionError
-} from '@fluentcommerce/fc-connect-sdk';
-
-class ErrorMonitor {
-  private errorCounts = new Map<string, number>();
-  private lastErrors = new Map<string, Date>();
-
-  recordError(error: Error): void {
-    let errorType = 'UNKNOWN';
-
-    if (error instanceof IngestionError) {
-      errorType = error.code;
-    } else if (error instanceof MappingError) {
-      errorType = 'MAPPING_ERROR';
-    } else if (error instanceof PathResolutionError) {
-      errorType = 'PATH_RESOLUTION_ERROR';
-    }
-
-    const count = this.errorCounts.get(errorType) || 0;
-    this.errorCounts.set(errorType, count + 1);
-    this.lastErrors.set(errorType, new Date());
-
-    // Alert if error rate is high
-    if (count + 1 > 10) {
-      this.alertHighErrorRate(errorType, count + 1);
-    }
-  }
-
-  getMetrics() {
-    return {
-      errorCounts: Object.fromEntries(this.errorCounts),
-      lastErrors: Object.fromEntries(this.lastErrors),
-      timestamp: new Date().toISOString()
-    };
-  }
-
-  private alertHighErrorRate(errorType: string, count: number): void {
-    console.error(`HIGH ERROR RATE: ${errorType} - ${count} errors`);
-    // Send alert to monitoring system (PagerDuty, Slack, etc.)
-  }
-}
-
-const errorMonitor = new ErrorMonitor();
-
-async function processWithMonitoring(data: any) {
-  try {
-    return await processOrder(data);
-  } catch (error) {
-    errorMonitor.recordError(error);
-    throw error;
-  }
-}
-```
-
-**Features:**
-- ✅ Tracks error counts by type
-- ✅ Records last occurrence of each error
-- ✅ Alerts on high error rates
-- ✅ Provides metrics for dashboards
-
-### Integration with Monitoring Systems
-
-Send errors to external monitoring:
-
-```typescript
-import { IngestionError } from '@fluentcommerce/fc-connect-sdk';
-
-async function processWithExternalMonitoring(data: any) {
-  try {
-    return await processOrder(data);
-  } catch (error) {
-    // Send to monitoring service
-    if (error instanceof IngestionError) {
-      await sendToDatadog({
-        metric: 'ingestion.error',
-        tags: [
-          `error_code:${error.code}`,
-          `retryable:${error.isRetryable()}`
-        ],
-        value: 1
-      });
-
-      await sendToSentry({
-        message: error.message,
-        level: 'error',
-        extra: error.toJSON()
-      });
-    }
-
-    throw error;
-  }
-}
-
-async function sendToDatadog(metric: any) {
-  // Datadog integration
-}
-
-async function sendToSentry(event: any) {
-  // Sentry integration
-}
-```
-
-## Stage-Specific Error Handling
-
-### Parsing Stage
-
-Handle parsing errors separately:
-
-```typescript
-async function safeParse(content: string, fileName: string): Promise<any> {
-  try {
-    const parser = new XMLParserService();
-    return await parser.parse(content);
-  } catch (error) {
-    if (error instanceof FileParsingError) {
-      logger.error('Parsing failed - permanent error', {
-        fileName,
-        lineNumber: error.lineNumber,
-        code: error.code
-      });
-
-      // Save to dead letter queue for manual review
-      await saveToDeadLetterQueue({
-        fileName,
-        content,
-        error: error.toJSON()
-      });
-
-      throw error;  // Don't retry
-    }
-    throw error;
-  }
-}
-```
-
-### Mapping Stage
-
-Handle mapping errors with detailed context:
-
-```typescript
-async function safeMap(parsed: any, context: any): Promise<any> {
-  try {
-    const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-    return await mapper.map(parsed);
-  } catch (error) {
-    if (error instanceof MappingError) {
-      logger.error('Mapping failed - check data or config', {
-        field: error.field,
-        sourcePath: error.sourcePath,
-        context
-      });
-
-      // Log sample data for debugging
-      await logSampleData({
-        field: error.field,
-        sourcePath: error.sourcePath,
-        sourceData: parsed
-      });
-
-      throw error;  // Don't retry
-    } else if (error instanceof PathResolutionError) {
-      logger.error('Path resolution failed - check config', {
-        path: error.path,
-        availablePaths: Object.keys(parsed)
-      });
-
-      throw error;  // Don't retry
-    }
-    throw error;
-  }
-}
-```
-
-### Execution Stage
-
-Handle API errors with retry logic:
-
-```typescript
-async function safeExecute(
-  payload: any,
-  maxRetries = 3
-): Promise<any> {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      const result = await client.graphql(payload);
-      return result.data;
-      
-    } catch (error) {
-      // Check for retryable GraphQL errors
-      if (error instanceof GraphQLExecutionError) {
-        const firstError = error.graphqlErrors[0];
-        if (firstError.extensions?.code === 'TIMEOUT' && attempt < maxRetries) {
-          const delay = Math.pow(2, attempt) * 1000;
-          logger.warn(`GraphQL timeout, retrying in ${delay}ms`, { attempt });
-          await new Promise(resolve => setTimeout(resolve, delay));
-          continue;
-        }
-        throw error;
-      }
-
-      if (error instanceof IngestionError &&
-          error.isRetryable() &&
-          attempt < maxRetries) {
-
-        const delay = Math.pow(2, attempt) * 1000;
-        logger.warn(`Retrying after ${delay}ms`, { attempt, error: error.code });
-        await new Promise(resolve => setTimeout(resolve, delay));
-        continue;
-      }
-
-      throw error;
-    }
-  }
-
-  throw new Error('Max retries exceeded');
-}
-```
-
-## Error Context Enrichment
-
-### Adding Context to Errors
-
-Enrich errors with business context:
-
-```typescript
-async function processOrderWithContext(xmlContent: string, metadata: any) {
-  try {
-    return await processOrder(xmlContent);
-  } catch (error) {
-    // Enrich error with business context
-    const enrichedError = new Error(error.message);
-    enrichedError.cause = error;
-    enrichedError.context = {
-      ...metadata,
-      timestamp: new Date().toISOString(),
-      environment: process.env.NODE_ENV,
-      version: process.env.APP_VERSION
-    };
-
-    if (error instanceof IngestionError) {
-      enrichedError.context.errorCode = error.code;
-      enrichedError.context.retryable = error.isRetryable();
-      enrichedError.context.originalContext = error.context;
-    }
-
-    logger.error('Order processing failed with context:', enrichedError.context);
-    throw enrichedError;
-  }
-}
-```
-
-## Key Takeaways
-
-- 🎯 **Always use try-catch** - Never call SDK methods without error handling
-- 🎯 **Check error types** - Use `instanceof` for specific handling
-- 🎯 **Re-throw errors** - Don't silence failures
-- 🎯 **Log with context** - Include all relevant error details
-- 🎯 **Monitor patterns** - Track error rates for alerting
-- 🎯 **Enrich errors** - Add business context before logging
-
-## Practice Exercise
-
-Improve this error handling code:
-
-```typescript
-// ❌ POOR ERROR HANDLING
-async function processData(data: any) {
-  try {
-    const result = await client.graphql(query);
-    return result.data;
-  } catch (error) {
-    console.log('Error');
-  }
-}
-```
-
-<details>
-<summary>Click to see improved version</summary>
-
-```typescript
-// ✅ IMPROVED ERROR HANDLING
-import {
-  FileParsingError,
-  MappingError,
-  IngestionError
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processData(data: any, context: any) {
-  try {
-    const result = await client.graphql(query);
-
-    if (result.errors) {
-      throw new Error(`GraphQL error: ${result.errors[0].message}`);
-    }
-
-    return result.data;
-
-  } catch (error) {
-    // Log with full context
-    logger.error('Data processing failed:', {
-      context,
-      error: error instanceof IngestionError ? error.toJSON() : error.message
-    });
-
-    // Check if retryable
-    if (error instanceof IngestionError && error.isRetryable()) {
-      return scheduleRetry(data, context);
-    }
-
-    // Re-throw for upstream handling
-    throw error;
-  }
-}
-```
-
-</details>
-
-## Next Steps
-
-Continue to [Module 6: Retry Strategies →](./error-handling-06-retry-strategies.md) to learn advanced retry patterns with exponential backoff.
-
----
-
-**Previous:** [← Module 4: Error Scenarios](./error-handling-04-error-scenarios.md)
-**Next:** [Module 6: Retry Strategies →](./error-handling-06-retry-strategies.md)
+# Module 5: Calling Patterns
+
+**Level:** Intermediate
+**Estimated Time:** 30 minutes
+
+## Overview
+
+This module provides practical code patterns for handling errors in your Fluent Commerce integrations, from basic try-catch blocks to comprehensive error handling with monitoring.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Write basic error handling code with try-catch
+- ✅ Implement comprehensive error handling for production systems
+- ✅ Add error monitoring and metrics collection
+- ✅ Know when to retry vs when to fail immediately
+
+## Basic Error Handling
+
+### Logging Setup
+
+**First, set up logging based on your runtime:**
+
+```typescript
+// Standalone (Node.js/Deno)
+import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'OrderProcessing' });
+
+// Versori Platform
+const { log: logger } = ctx;  // Use native platform log
+```
+
+### Minimal Pattern
+
+The simplest error handling pattern - catch and log:
+
+```typescript
+import {
+  XMLParserService,
+  GraphQLMutationMapper,
+  FluentClient,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Standalone
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'OrderProcessing' });
+
+// Versori Platform
+// const { log: logger } = ctx;
+
+async function processOrder(xmlContent: string) {
+  try {
+    // Parse XML
+    const parser = new XMLParserService();
+    const parsed = await parser.parse(xmlContent);
+
+    // Map to GraphQL mutation
+    const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+    const payload = await mapper.map(parsed);
+
+    // Execute mutation
+    // Throws GraphQLExecutionError on failure
+    const result = await client.graphql(payload);
+
+    return result.data;
+
+  } catch (error) {
+    logger.error('Order processing failed', error);
+    throw error;  // Re-throw for upstream handling
+  }
+}
+```
+
+**Key points:**
+- ✅ Wraps all operations in try-catch
+- ✅ Logs the error
+- ✅ Re-throws error (doesn't silence failures)
+- ❌ No specific error type handling
+- ❌ No retry logic
+
+### Intermediate Pattern with Type Checking
+
+Add specific handling for different error types:
+
+```typescript
+import {
+  XMLParserService,
+  GraphQLMutationMapper,
+  FluentClient,
+  FileParsingError,
+  PathResolutionError,
+  MappingError,
+  IngestionError,
+  GraphQLExecutionError
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processOrder(xmlContent: string) {
+  try {
+    // Parse XML
+    const parser = new XMLParserService();
+    const parsed = await parser.parse(xmlContent);
+
+    // Map to GraphQL mutation
+    const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+    const payload = await mapper.map(parsed);
+
+    // Execute mutation (only if no errors above)
+    // Throws GraphQLExecutionError on failure
+    const result = await client.graphql(payload);
+
+    return result.data;  // ✅ Complete data or nothing
+
+  } catch (error) {
+    // ✅ IMPORTANT: No partial data - mutation never executed or was rejected
+
+    if (error instanceof GraphQLExecutionError) {
+      // GraphQL errors from Fluent
+      logger.error('GraphQL error:', {
+        message: error.message,
+        errors: error.getErrorMessages(),
+        query: error.query
+      });
+      
+      // Classify errors to determine retry strategy
+      if (error.isAuthError()) {
+        // Auth error
+      } else if (error.isValidationError()) {
+        // Validation error
+      }
+      
+      throw error;
+    } else if (error instanceof FileParsingError) {
+      // XML parsing failed
+      logger.error('Invalid XML file:', {
+        code: error.code,
+        fileName: error.fileName,
+        lineNumber: error.lineNumber,
+        message: error.message
+      });
+      // Alert user: File is corrupt or invalid format
+      throw error;  // Don't retry
+
+    } else if (error instanceof PathResolutionError) {
+      // Wrong path in mapping config
+      logger.error('Path resolution failed:', {
+        path: error.path,
+        message: error.message
+      });
+      // Alert developer: Fix mapping configuration
+      throw error;  // Don't retry
+
+    } else if (error instanceof MappingError) {
+      // Required field missing or type mismatch
+      logger.error('Mapping failed:', {
+        field: error.field,
+        sourcePath: error.sourcePath,
+        message: error.message
+      });
+      // Alert developer: Data doesn't match mapping expectations
+      throw error;  // Don't retry
+
+    } else if (error instanceof IngestionError) {
+      logger.error('Ingestion error:', error.toJSON());
+
+      // Retry if transient error
+      if (error.isRetryable()) {
+        return scheduleRetry();
+      }
+      throw error;  // Non-retryable
+    }
+
+    // Unknown error
+    throw error;
+  }
+}
+```
+
+**Key points:**
+- ✅ Checks specific error types with `instanceof`
+- ✅ Logs error-specific context
+- ✅ Uses `error.isRetryable()` for retry decisions
+- ✅ Different handling for different error types
+- ✅ Clear comments explaining each case
+
+## Comprehensive Error Handling
+
+### Production-Ready Pattern with Retry Logic
+
+Complete error handling for production systems:
+
+```typescript
+import {
+  createClient,
+  XMLParserService,
+  GraphQLMutationMapper,
+  FileParsingError,
+  PathResolutionError,
+  MappingError,
+  ValidationError,
+  IngestionError,
+  IngestionErrorCode,
+  GraphQLExecutionError,
+  FluentAPIError
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processOrderWithRetry(
+  xmlContent: string,
+  maxRetries = 3
+): Promise<any> {
+  let attempt = 0;
+
+  while (attempt < maxRetries) {
+    try {
+      attempt++;
+
+      // Parse XML
+      const parser = new XMLParserService();
+      let parsed;
+
+      try {
+        parsed = await parser.parse(xmlContent);
+      } catch (error) {
+        if (error instanceof FileParsingError) {
+          // Parse error = permanent failure, don't retry
+          logger.error('XML parse error (permanent):', {
+            code: error.code,
+            fileName: error.fileName,
+            message: error.message
+          });
+          throw error;  // Don't retry
+        }
+        throw error;
+      }
+
+      // Map to mutation
+      const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+      let payload;
+
+      try {
+        payload = await mapper.map(parsed);
+      } catch (error) {
+        if (error instanceof PathResolutionError) {
+          // Wrong path = permanent failure (config issue)
+          logger.error('Path error (permanent):', {
+            path: error.path,
+            message: error.message
+          });
+          throw error;  // Don't retry
+
+        } else if (error instanceof MappingError) {
+          // Mapping error = permanent failure (data/config issue)
+          logger.error('Mapping error (permanent):', {
+            field: error.field,
+            sourcePath: error.sourcePath,
+            message: error.message
+          });
+          throw error;  // Don't retry
+        }
+        throw error;
+      }
+
+      // Execute mutation
+      const result = await client.graphql(payload);
+
+      // Success - return complete data
+      return result.data;
+
+    } catch (error) {
+      // Check if error is retryable
+
+      // 1. GraphQL Execution Error (e.g. Timeout/Network in GraphQL response)
+      if (error instanceof GraphQLExecutionError) {
+         const graphqlError = error.graphqlErrors[0];
+         
+         if (graphqlError.extensions?.code === 'TIMEOUT' || 
+             graphqlError.extensions?.code === 'NETWORK_ERROR') {
+            
+            if (attempt < maxRetries) {
+              await delay(1000 * attempt);
+              continue;  // Retry
+            }
+         }
+         // Permanent GraphQL error
+         throw error;
+      }
+      
+      // 2. Ingestion Error (Network, etc.)
+      if (error instanceof IngestionError && error.isRetryable()) {
+        if (attempt < maxRetries) {
+          logger.warn(`Retryable error, attempt ${attempt}/${maxRetries}`, {
+            code: error.code,
+            message: error.message
+          });
+
+          // Exponential backoff
+          await delay(1000 * Math.pow(2, attempt - 1));
+          continue;
+        }
+      }
+      
+      // 3. Fluent API Error (HTTP 5xx)
+      if (error instanceof FluentAPIError && error.statusCode >= 500) {
+         if (attempt < maxRetries) {
+            await delay(1000 * attempt);
+            continue;
+         }
+      }
+
+      // Non-retryable error or max retries exceeded
+      logger.error('Order processing failed:', {
+        attempt,
+        error: error instanceof IngestionError ? error.toJSON() : error.message
+      });
+
+      throw error;
+    }
+  }
+
+  throw new Error('Max retries exceeded');
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+```
+
+**Key points:**
+- ✅ Retry loop with max attempts
+- ✅ Specific handling at each stage (parse, map, execute)
+- ✅ Permanent errors immediately thrown (no retry)
+- ✅ Transient errors retried with exponential backoff
+- ✅ GraphQL errors classified by code
+- ✅ Detailed logging at each stage
+
+## Error Handling with Monitoring
+
+### Adding Metrics Collection
+
+Track error patterns for alerting and analysis:
+
+```typescript
+import {
+  IngestionError,
+  IngestionErrorCode,
+  MappingError,
+  PathResolutionError
+} from '@fluentcommerce/fc-connect-sdk';
+
+class ErrorMonitor {
+  private errorCounts = new Map<string, number>();
+  private lastErrors = new Map<string, Date>();
+
+  recordError(error: Error): void {
+    let errorType = 'UNKNOWN';
+
+    if (error instanceof IngestionError) {
+      errorType = error.code;
+    } else if (error instanceof MappingError) {
+      errorType = 'MAPPING_ERROR';
+    } else if (error instanceof PathResolutionError) {
+      errorType = 'PATH_RESOLUTION_ERROR';
+    }
+
+    const count = this.errorCounts.get(errorType) || 0;
+    this.errorCounts.set(errorType, count + 1);
+    this.lastErrors.set(errorType, new Date());
+
+    // Alert if error rate is high
+    if (count + 1 > 10) {
+      this.alertHighErrorRate(errorType, count + 1);
+    }
+  }
+
+  getMetrics() {
+    return {
+      errorCounts: Object.fromEntries(this.errorCounts),
+      lastErrors: Object.fromEntries(this.lastErrors),
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  private alertHighErrorRate(errorType: string, count: number): void {
+    console.error(`HIGH ERROR RATE: ${errorType} - ${count} errors`);
+    // Send alert to monitoring system (PagerDuty, Slack, etc.)
+  }
+}
+
+const errorMonitor = new ErrorMonitor();
+
+async function processWithMonitoring(data: any) {
+  try {
+    return await processOrder(data);
+  } catch (error) {
+    errorMonitor.recordError(error);
+    throw error;
+  }
+}
+```
+
+**Features:**
+- ✅ Tracks error counts by type
+- ✅ Records last occurrence of each error
+- ✅ Alerts on high error rates
+- ✅ Provides metrics for dashboards
+
+### Integration with Monitoring Systems
+
+Send errors to external monitoring:
+
+```typescript
+import { IngestionError } from '@fluentcommerce/fc-connect-sdk';
+
+async function processWithExternalMonitoring(data: any) {
+  try {
+    return await processOrder(data);
+  } catch (error) {
+    // Send to monitoring service
+    if (error instanceof IngestionError) {
+      await sendToDatadog({
+        metric: 'ingestion.error',
+        tags: [
+          `error_code:${error.code}`,
+          `retryable:${error.isRetryable()}`
+        ],
+        value: 1
+      });
+
+      await sendToSentry({
+        message: error.message,
+        level: 'error',
+        extra: error.toJSON()
+      });
+    }
+
+    throw error;
+  }
+}
+
+async function sendToDatadog(metric: any) {
+  // Datadog integration
+}
+
+async function sendToSentry(event: any) {
+  // Sentry integration
+}
+```
+
+## Stage-Specific Error Handling
+
+### Parsing Stage
+
+Handle parsing errors separately:
+
+```typescript
+async function safeParse(content: string, fileName: string): Promise<any> {
+  try {
+    const parser = new XMLParserService();
+    return await parser.parse(content);
+  } catch (error) {
+    if (error instanceof FileParsingError) {
+      logger.error('Parsing failed - permanent error', {
+        fileName,
+        lineNumber: error.lineNumber,
+        code: error.code
+      });
+
+      // Save to dead letter queue for manual review
+      await saveToDeadLetterQueue({
+        fileName,
+        content,
+        error: error.toJSON()
+      });
+
+      throw error;  // Don't retry
+    }
+    throw error;
+  }
+}
+```
+
+### Mapping Stage
+
+Handle mapping errors with detailed context:
+
+```typescript
+async function safeMap(parsed: any, context: any): Promise<any> {
+  try {
+    const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+    return await mapper.map(parsed);
+  } catch (error) {
+    if (error instanceof MappingError) {
+      logger.error('Mapping failed - check data or config', {
+        field: error.field,
+        sourcePath: error.sourcePath,
+        context
+      });
+
+      // Log sample data for debugging
+      await logSampleData({
+        field: error.field,
+        sourcePath: error.sourcePath,
+        sourceData: parsed
+      });
+
+      throw error;  // Don't retry
+    } else if (error instanceof PathResolutionError) {
+      logger.error('Path resolution failed - check config', {
+        path: error.path,
+        availablePaths: Object.keys(parsed)
+      });
+
+      throw error;  // Don't retry
+    }
+    throw error;
+  }
+}
+```
+
+### Execution Stage
+
+Handle API errors with retry logic:
+
+```typescript
+async function safeExecute(
+  payload: any,
+  maxRetries = 3
+): Promise<any> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const result = await client.graphql(payload);
+      return result.data;
+      
+    } catch (error) {
+      // Check for retryable GraphQL errors
+      if (error instanceof GraphQLExecutionError) {
+        const firstError = error.graphqlErrors[0];
+        if (firstError.extensions?.code === 'TIMEOUT' && attempt < maxRetries) {
+          const delay = Math.pow(2, attempt) * 1000;
+          logger.warn(`GraphQL timeout, retrying in ${delay}ms`, { attempt });
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+        throw error;
+      }
+
+      if (error instanceof IngestionError &&
+          error.isRetryable() &&
+          attempt < maxRetries) {
+
+        const delay = Math.pow(2, attempt) * 1000;
+        logger.warn(`Retrying after ${delay}ms`, { attempt, error: error.code });
+        await new Promise(resolve => setTimeout(resolve, delay));
+        continue;
+      }
+
+      throw error;
+    }
+  }
+
+  throw new Error('Max retries exceeded');
+}
+```
+
+## Error Context Enrichment
+
+### Adding Context to Errors
+
+Enrich errors with business context:
+
+```typescript
+async function processOrderWithContext(xmlContent: string, metadata: any) {
+  try {
+    return await processOrder(xmlContent);
+  } catch (error) {
+    // Enrich error with business context
+    const enrichedError = new Error(error.message);
+    enrichedError.cause = error;
+    enrichedError.context = {
+      ...metadata,
+      timestamp: new Date().toISOString(),
+      environment: process.env.NODE_ENV,
+      version: process.env.APP_VERSION
+    };
+
+    if (error instanceof IngestionError) {
+      enrichedError.context.errorCode = error.code;
+      enrichedError.context.retryable = error.isRetryable();
+      enrichedError.context.originalContext = error.context;
+    }
+
+    logger.error('Order processing failed with context:', enrichedError.context);
+    throw enrichedError;
+  }
+}
+```
+
+## Key Takeaways
+
+- 🎯 **Always use try-catch** - Never call SDK methods without error handling
+- 🎯 **Check error types** - Use `instanceof` for specific handling
+- 🎯 **Re-throw errors** - Don't silence failures
+- 🎯 **Log with context** - Include all relevant error details
+- 🎯 **Monitor patterns** - Track error rates for alerting
+- 🎯 **Enrich errors** - Add business context before logging
+
+## Practice Exercise
+
+Improve this error handling code:
+
+```typescript
+// ❌ POOR ERROR HANDLING
+async function processData(data: any) {
+  try {
+    const result = await client.graphql(query);
+    return result.data;
+  } catch (error) {
+    console.log('Error');
+  }
+}
+```
+
+<details>
+<summary>Click to see improved version</summary>
+
+```typescript
+// ✅ IMPROVED ERROR HANDLING
+import {
+  FileParsingError,
+  MappingError,
+  IngestionError
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processData(data: any, context: any) {
+  try {
+    const result = await client.graphql(query);
+
+    if (result.errors) {
+      throw new Error(`GraphQL error: ${result.errors[0].message}`);
+    }
+
+    return result.data;
+
+  } catch (error) {
+    // Log with full context
+    logger.error('Data processing failed:', {
+      context,
+      error: error instanceof IngestionError ? error.toJSON() : error.message
+    });
+
+    // Check if retryable
+    if (error instanceof IngestionError && error.isRetryable()) {
+      return scheduleRetry(data, context);
+    }
+
+    // Re-throw for upstream handling
+    throw error;
+  }
+}
+```
+
+</details>
+
+## Next Steps
+
+Continue to [Module 6: Retry Strategies →](./error-handling-06-retry-strategies.md) to learn advanced retry patterns with exponential backoff.
+
+---
+
+**Previous:** [← Module 4: Error Scenarios](./error-handling-04-error-scenarios.md)
+**Next:** [Module 6: Retry Strategies →](./error-handling-06-retry-strategies.md)