@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/patterns/patterns-error-handling-retry.md

@@ -1,511 +1,511 @@
-# Pattern: Error Handling & Retry Strategies
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Focused guide on error handling, retry logic, and graceful degradation
-
-**Type**: Reusable Pattern
-
-**Complexity**: Low-Medium
-
-**Lines**: ~140 lines
-
-## When to Use This Pattern
-
-- Network failures and timeouts
-- API rate limiting
-- Transient errors
-- Batch processing errors
-- File processing failures
-- State management conflicts
-
-## SDK Error Classes
-
-The FC Connect SDK provides typed error classes for robust error handling:
-
-```typescript
-import {
-  IngestionError, // Base class with error codes
-  IngestionErrorCode, // Machine-readable error codes
-  ConfigurationError, // Config validation errors
-  FileParsingError, // XML/CSV/Parquet parsing errors
-  ValidationError, // Data validation errors
-  AggregateIngestionError, // Multiple failures aggregated
-  IngestionErrorFactory, // Create structured errors
-} from '@fluentcommerce/fc-connect-sdk';
-```
-
-## Common Error Handling Patterns
-
-### 1. Basic Try-Catch with Logging
-
-```typescript
-// FC Connect SDK (latest)
-// Install: npm install @fluentcommerce/fc-connect-sdk@latest
-// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
-// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
-
-import {
-  IngestionError,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-const logger = createConsoleLogger();
-
-async function processFile(fileName: string) {
-  try {
-    const data = await readFile(fileName);
-    const result = await sendBatch(data);
-    logger.info('File processed successfully', { fileName, recordCount: result.count });
-    return result;
-  } catch (error) {
-    if (error instanceof IngestionError) {
-      // Structured error with error code and context
-      logger.error('Processing failed', error.toJSON());
-      // Re-throw to prevent silent failures
-      throw error;
-    }
-
-    // Unexpected error - wrap and re-throw
-    logger.error('Unexpected error', { message: error.message, stack: error.stack });
-    throw IngestionErrorFactory.fromError(error);
-  }
-}
-```
-
-### 2. GraphQL Error Classification & Retry
-
-```typescript
-import { 
-  createClient, 
-  GraphQLMutationMapper,
-  classifyErrors,
-  type GraphQLError 
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function executeMutationWithRetry(
-  client: FluentClient,
-  mapper: GraphQLMutationMapper,
-  sourceData: any,
-  maxRetries = 3
-) {
-  // Map source data to GraphQL mutation
-  const mappingResult = await mapper.mapSafe(sourceData);
-  
-  if (!mappingResult.success) {
-    throw new Error(`Mapping failed: ${mappingResult.errors?.join(', ')}`);
-  }
-
-  // Execute mutation with retry logic
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    const result = await client.graphql({
-      query: mappingResult.query,
-      variables: mappingResult.variables,
-    });
-
-    if (!result.errors) {
-      return result; // Success
-    }
-
-    // Classify GraphQL errors
-    const classification = classifyErrors(result.errors);
-    
-    logger.info(`GraphQL error (attempt ${attempt}/${maxRetries}):`, {
-      errorCode: classification.errorCode,
-      retryable: classification.retryable,
-      action: classification.action,
-    });
-
-    // Don't retry non-retryable errors
-    if (!classification.retryable) {
-      throw new Error(classification.userMessage);
-    }
-
-    // Wait before retry (use recommended delay or exponential backoff)
-    if (attempt < maxRetries) {
-      const delay = classification.retryDelaySeconds || Math.pow(2, attempt) * 1000;
-      logger.info(`Retrying after ${delay}ms...`);
-      await new Promise(resolve => setTimeout(resolve, delay * 1000));
-    }
-  }
-
-  throw new Error('All retry attempts failed');
-}
-```
-
-### 3. Exponential Backoff Retry
-
-```typescript
-import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
-
-async function retryWithBackoff<T>(
-  operation: () => Promise<T>,
-  maxRetries: number = 3,
-  initialDelay: number = 1000
-): Promise<T> {
-  let lastError: Error;
-
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await operation();
-    } catch (error) {
-      lastError = error;
-
-      // Only retry if error is retryable
-      if (error instanceof IngestionError && !error.isRetryable()) {
-        console.error('Non-retryable error, stopping:', error.code);
-        throw error;
-      }
-
-      // Last attempt - throw error
-      if (attempt === maxRetries - 1) {
-        throw lastError;
-      }
-
-      // Calculate exponential backoff with jitter
-      const delay = initialDelay * Math.pow(2, attempt);
-      const jitter = Math.random() * 100;
-      console.log(`Retry ${attempt + 1}/${maxRetries} after ${delay + jitter}ms`);
-      await new Promise(resolve => setTimeout(resolve, delay + jitter));
-    }
-  }
-
-  throw lastError!;
-}
-
-// Usage
-const result = await retryWithBackoff(
-  () => client.sendBatch(jobId, batch),
-  3, // max retries
-  2000 // initial delay (2 seconds)
-);
-```
-
-### 3. Circuit Breaker Pattern
-
-```typescript
-class CircuitBreaker {
-  private failureCount = 0;
-  private lastFailureTime?: Date;
-  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
-
-  constructor(
-    private threshold: number = 5,
-    private timeout: number = 60000 // 60 seconds
-  ) {}
-
-  async execute<T>(operation: () => Promise<T>): Promise<T> {
-    // Check if circuit is open
-    if (this.state === 'OPEN') {
-      const timeSinceFailure = Date.now() - this.lastFailureTime!.getTime();
-      if (timeSinceFailure < this.timeout) {
-        throw new Error('Circuit breaker is OPEN - operation rejected');
-      }
-      // Timeout elapsed - try half-open
-      this.state = 'HALF_OPEN';
-    }
-
-    try {
-      const result = await operation();
-      // Success - reset circuit
-      this.failureCount = 0;
-      this.state = 'CLOSED';
-      return result;
-    } catch (error) {
-      this.failureCount++;
-      this.lastFailureTime = new Date();
-
-      // Open circuit if threshold exceeded
-      if (this.failureCount >= this.threshold) {
-        this.state = 'OPEN';
-        console.warn(`Circuit breaker opened after ${this.failureCount} failures`);
-      }
-
-      throw error;
-    }
-  }
-}
-
-// Usage
-const breaker = new CircuitBreaker(5, 60000);
-
-async function callAPI() {
-  return breaker.execute(() => client.sendBatch(jobId, batch));
-}
-```
-
-### 4. Batch Error Isolation
-
-```typescript
-import { AggregateIngestionError, IngestionError } from '@fluentcommerce/fc-connect-sdk';
-
-async function processBatchWithIsolation(records: any[]) {
-  const errors: IngestionError[] = [];
-  const successes: any[] = [];
-
-  for (const [index, record] of records.entries()) {
-    try {
-      const result = await processRecord(record);
-      successes.push(result);
-    } catch (error) {
-      // Isolate error to single record
-      const ingestionError =
-        error instanceof IngestionError
-          ? error
-          : IngestionErrorFactory.fromError(error, IngestionErrorCode.TRANSFORMATION_ERROR, {
-              recordIndex: index,
-              record,
-            });
-
-      errors.push(ingestionError);
-      logger.warn(`Record ${index} failed, continuing with remaining records`, {
-        recordIndex: index,
-        error: ingestionError.toJSON(),
-      });
-    }
-  }
-
-  // Log summary
-  logger.info('Batch processing complete', {
-    total: records.length,
-    successes: successes.length,
-    failures: errors.length,
-  });
-
-  // Throw aggregate if any failures
-  if (errors.length > 0) {
-    throw new AggregateIngestionError(
-      `${errors.length} of ${records.length} records failed`,
-      errors
-    );
-  }
-
-  return successes;
-}
-```
-
-### 5. Graceful Degradation
-
-```typescript
-async function fetchWithFallback(primarySource: string, fallbackSource: string) {
-  try {
-    // Try primary source
-    return await fetch(primarySource);
-  } catch (primaryError) {
-    logger.warn('Primary source failed, trying fallback', {
-      primarySource,
-      error: primaryError.message,
-    });
-
-    try {
-      // Fallback to secondary source
-      return await fetch(fallbackSource);
-    } catch (fallbackError) {
-      logger.error('Both primary and fallback sources failed', {
-        primaryError: primaryError.message,
-        fallbackError: fallbackError.message,
-      });
-
-      // Return cached data or empty result as last resort
-      return getCachedData() || { data: [], cached: true };
-    }
-  }
-}
-```
-
-### 6. Error Monitoring and Alerting
-
-```typescript
-import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
-
-class ErrorMonitor {
-  private errorCounts = new Map<string, number>();
-  private errorWindow = new Map<string, Date[]>();
-  private readonly windowSize = 5 * 60 * 1000; // 5 minutes
-
-  recordError(error: Error): void {
-    const errorType = error instanceof IngestionError ? error.code : 'UNKNOWN';
-
-    // Increment counter
-    const count = (this.errorCounts.get(errorType) || 0) + 1;
-    this.errorCounts.set(errorType, count);
-
-    // Track in time window
-    const timestamps = this.errorWindow.get(errorType) || [];
-    timestamps.push(new Date());
-    this.errorWindow.set(errorType, timestamps);
-
-    // Clean old entries
-    this.cleanupWindow(errorType);
-
-    // Check for high error rate
-    const recentErrors = this.errorWindow.get(errorType)!.length;
-    if (recentErrors > 10) {
-      this.alertHighErrorRate(errorType, recentErrors);
-    }
-  }
-
-  private cleanupWindow(errorType: string): void {
-    const timestamps = this.errorWindow.get(errorType) || [];
-    const cutoff = Date.now() - this.windowSize;
-    const recent = timestamps.filter(t => t.getTime() > cutoff);
-    this.errorWindow.set(errorType, recent);
-  }
-
-  private alertHighErrorRate(errorType: string, count: number): void {
-    console.error(`ALERT: High error rate detected - ${errorType}: ${count} errors in 5 minutes`);
-    // Send to monitoring system (DataDog, CloudWatch, etc.)
-    // sendAlert({ type: errorType, count, window: '5m' });
-  }
-
-  getMetrics() {
-    return {
-      totalErrors: Object.fromEntries(this.errorCounts),
-      recentErrors: Object.fromEntries(
-        Array.from(this.errorWindow.entries()).map(([type, timestamps]) => [
-          type,
-          timestamps.length,
-        ])
-      ),
-      timestamp: new Date().toISOString(),
-    };
-  }
-}
-
-// Usage
-const monitor = new ErrorMonitor();
-
-try {
-  await processFile(fileName);
-} catch (error) {
-  monitor.recordError(error);
-  throw error;
-}
-```
-
-## Best Practices
-
-### Do's
-
-1. **Always Check Error Type**
-
-   ```typescript
-   if (error instanceof IngestionError && error.isRetryable()) {
-     return scheduleRetry();
-   }
-   ```
-
-2. **Use Structured Logging**
-
-   ```typescript
-   logger.error('Operation failed', error.toJSON());
-   ```
-
-3. **Add Context to Errors**
-
-   ```typescript
-   throw new TransformationError('Failed to parse quantity', recordIndex, 'quantity', {
-     record,
-     originalValue,
-   });
-   ```
-
-4. **Re-throw After Handling**
-
-   ```typescript
-   try {
-     await operation();
-   } catch (error) {
-     logger.error('Failed', error);
-     throw error; // Don't swallow errors
-   }
-   ```
-
-5. **Distinguish Retryable Errors**
-   ```typescript
-   // Retryable: NETWORK_ERROR, TIMEOUT_ERROR, RATE_LIMIT_ERROR
-   // Non-retryable: PARSE_ERROR, VALIDATION_ERROR, CONFIGURATION_ERROR
-   ```
-
-### Don'ts
-
-1. **Don't Swallow Errors**
-
-   ```typescript
-   // ❌ WRONG
-   try {
-     await operation();
-   } catch {}
-
-   // ✅ CORRECT
-   try {
-     await operation();
-   } catch (error) {
-     logger.error('Failed', error);
-     throw error;
-   }
-   ```
-
-2. **Don't Retry Non-Retryable Errors**
-
-   ```typescript
-   // ❌ WRONG - Retrying parse errors wastes resources
-   await retry(() => parseXML(invalidXML));
-
-   // ✅ CORRECT - Check if retryable first
-   if (error.isRetryable()) await retry(operation);
-   ```
-
-3. **Don't Use Generic Error Messages**
-
-   ```typescript
-   // ❌ WRONG
-   throw new Error('Failed');
-
-   // ✅ CORRECT
-   throw new FileParsingError('Invalid CSV: missing header row', fileName, 1);
-   ```
-
-4. **Don't Ignore Error Context**
-
-   ```typescript
-   // ❌ WRONG
-   console.log(error.message);
-
-   // ✅ CORRECT
-   console.log(error.toJSON()); // Includes code, context, timestamp, etc.
-   ```
-
-## Retryable vs Non-Retryable Errors
-
-```typescript
-// RETRYABLE - Transient failures
-IngestionErrorCode.NETWORK_ERROR;
-IngestionErrorCode.TIMEOUT_ERROR;
-IngestionErrorCode.RATE_LIMIT_ERROR;
-IngestionErrorCode.LOCK_ACQUISITION_FAILED;
-
-// NON-RETRYABLE - Permanent failures
-IngestionErrorCode.PARSE_ERROR;
-IngestionErrorCode.VALIDATION_ERROR;
-IngestionErrorCode.REQUIRED_FIELD_MISSING;
-IngestionErrorCode.CONFIGURATION_ERROR;
-IngestionErrorCode.FIELD_MAPPING_ERROR;
-IngestionErrorCode.INVALID_FILE_FORMAT;
-```
-
-## Related Patterns
-
-- [Batch Processing Pattern](../../03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-02-batch-processing.md) - Handling batch-level errors
-- [State Management Pattern](../../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-07-state-management.md) - State-related error handling
-- [Configuration Pattern](../../04-REFERENCE/platforms/versori/modules/platforms-versori-02-quick-start.md) - Config validation errors
-
-## Related Documentation
-
-- [Complete Error Handling Guide](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
-- [GraphQL Mapping Error Handling](../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md)
-- [API Reference - Error Classes](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
+# Pattern: Error Handling & Retry Strategies
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Focused guide on error handling, retry logic, and graceful degradation
+
+**Type**: Reusable Pattern
+
+**Complexity**: Low-Medium
+
+**Lines**: ~140 lines
+
+## When to Use This Pattern
+
+- Network failures and timeouts
+- API rate limiting
+- Transient errors
+- Batch processing errors
+- File processing failures
+- State management conflicts
+
+## SDK Error Classes
+
+The FC Connect SDK provides typed error classes for robust error handling:
+
+```typescript
+import {
+  IngestionError, // Base class with error codes
+  IngestionErrorCode, // Machine-readable error codes
+  ConfigurationError, // Config validation errors
+  FileParsingError, // XML/CSV/Parquet parsing errors
+  ValidationError, // Data validation errors
+  AggregateIngestionError, // Multiple failures aggregated
+  IngestionErrorFactory, // Create structured errors
+} from '@fluentcommerce/fc-connect-sdk';
+```
+
+## Common Error Handling Patterns
+
+### 1. Basic Try-Catch with Logging
+
+```typescript
+// FC Connect SDK (latest)
+// Install: npm install @fluentcommerce/fc-connect-sdk@latest
+// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
+// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
+
+import {
+  IngestionError,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+const logger = createConsoleLogger();
+
+async function processFile(fileName: string) {
+  try {
+    const data = await readFile(fileName);
+    const result = await sendBatch(data);
+    logger.info('File processed successfully', { fileName, recordCount: result.count });
+    return result;
+  } catch (error) {
+    if (error instanceof IngestionError) {
+      // Structured error with error code and context
+      logger.error('Processing failed', error.toJSON());
+      // Re-throw to prevent silent failures
+      throw error;
+    }
+
+    // Unexpected error - wrap and re-throw
+    logger.error('Unexpected error', { message: error.message, stack: error.stack });
+    throw IngestionErrorFactory.fromError(error);
+  }
+}
+```
+
+### 2. GraphQL Error Classification & Retry
+
+```typescript
+import { 
+  createClient, 
+  GraphQLMutationMapper,
+  classifyErrors,
+  type GraphQLError 
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function executeMutationWithRetry(
+  client: FluentClient,
+  mapper: GraphQLMutationMapper,
+  sourceData: any,
+  maxRetries = 3
+) {
+  // Map source data to GraphQL mutation
+  const mappingResult = await mapper.mapSafe(sourceData);
+  
+  if (!mappingResult.success) {
+    throw new Error(`Mapping failed: ${mappingResult.errors?.join(', ')}`);
+  }
+
+  // Execute mutation with retry logic
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const result = await client.graphql({
+      query: mappingResult.query,
+      variables: mappingResult.variables,
+    });
+
+    if (!result.errors) {
+      return result; // Success
+    }
+
+    // Classify GraphQL errors
+    const classification = classifyErrors(result.errors);
+    
+    logger.info(`GraphQL error (attempt ${attempt}/${maxRetries}):`, {
+      errorCode: classification.errorCode,
+      retryable: classification.retryable,
+      action: classification.action,
+    });
+
+    // Don't retry non-retryable errors
+    if (!classification.retryable) {
+      throw new Error(classification.userMessage);
+    }
+
+    // Wait before retry (use recommended delay or exponential backoff)
+    if (attempt < maxRetries) {
+      const delay = classification.retryDelaySeconds || Math.pow(2, attempt) * 1000;
+      logger.info(`Retrying after ${delay}ms...`);
+      await new Promise(resolve => setTimeout(resolve, delay * 1000));
+    }
+  }
+
+  throw new Error('All retry attempts failed');
+}
+```
+
+### 3. Exponential Backoff Retry
+
+```typescript
+import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
+
+async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  maxRetries: number = 3,
+  initialDelay: number = 1000
+): Promise<T> {
+  let lastError: Error;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+
+      // Only retry if error is retryable
+      if (error instanceof IngestionError && !error.isRetryable()) {
+        console.error('Non-retryable error, stopping:', error.code);
+        throw error;
+      }
+
+      // Last attempt - throw error
+      if (attempt === maxRetries - 1) {
+        throw lastError;
+      }
+
+      // Calculate exponential backoff with jitter
+      const delay = initialDelay * Math.pow(2, attempt);
+      const jitter = Math.random() * 100;
+      console.log(`Retry ${attempt + 1}/${maxRetries} after ${delay + jitter}ms`);
+      await new Promise(resolve => setTimeout(resolve, delay + jitter));
+    }
+  }
+
+  throw lastError!;
+}
+
+// Usage
+const result = await retryWithBackoff(
+  () => client.sendBatch(jobId, batch),
+  3, // max retries
+  2000 // initial delay (2 seconds)
+);
+```
+
+### 3. Circuit Breaker Pattern
+
+```typescript
+class CircuitBreaker {
+  private failureCount = 0;
+  private lastFailureTime?: Date;
+  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
+
+  constructor(
+    private threshold: number = 5,
+    private timeout: number = 60000 // 60 seconds
+  ) {}
+
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    // Check if circuit is open
+    if (this.state === 'OPEN') {
+      const timeSinceFailure = Date.now() - this.lastFailureTime!.getTime();
+      if (timeSinceFailure < this.timeout) {
+        throw new Error('Circuit breaker is OPEN - operation rejected');
+      }
+      // Timeout elapsed - try half-open
+      this.state = 'HALF_OPEN';
+    }
+
+    try {
+      const result = await operation();
+      // Success - reset circuit
+      this.failureCount = 0;
+      this.state = 'CLOSED';
+      return result;
+    } catch (error) {
+      this.failureCount++;
+      this.lastFailureTime = new Date();
+
+      // Open circuit if threshold exceeded
+      if (this.failureCount >= this.threshold) {
+        this.state = 'OPEN';
+        console.warn(`Circuit breaker opened after ${this.failureCount} failures`);
+      }
+
+      throw error;
+    }
+  }
+}
+
+// Usage
+const breaker = new CircuitBreaker(5, 60000);
+
+async function callAPI() {
+  return breaker.execute(() => client.sendBatch(jobId, batch));
+}
+```
+
+### 4. Batch Error Isolation
+
+```typescript
+import { AggregateIngestionError, IngestionError } from '@fluentcommerce/fc-connect-sdk';
+
+async function processBatchWithIsolation(records: any[]) {
+  const errors: IngestionError[] = [];
+  const successes: any[] = [];
+
+  for (const [index, record] of records.entries()) {
+    try {
+      const result = await processRecord(record);
+      successes.push(result);
+    } catch (error) {
+      // Isolate error to single record
+      const ingestionError =
+        error instanceof IngestionError
+          ? error
+          : IngestionErrorFactory.fromError(error, IngestionErrorCode.TRANSFORMATION_ERROR, {
+              recordIndex: index,
+              record,
+            });
+
+      errors.push(ingestionError);
+      logger.warn(`Record ${index} failed, continuing with remaining records`, {
+        recordIndex: index,
+        error: ingestionError.toJSON(),
+      });
+    }
+  }
+
+  // Log summary
+  logger.info('Batch processing complete', {
+    total: records.length,
+    successes: successes.length,
+    failures: errors.length,
+  });
+
+  // Throw aggregate if any failures
+  if (errors.length > 0) {
+    throw new AggregateIngestionError(
+      `${errors.length} of ${records.length} records failed`,
+      errors
+    );
+  }
+
+  return successes;
+}
+```
+
+### 5. Graceful Degradation
+
+```typescript
+async function fetchWithFallback(primarySource: string, fallbackSource: string) {
+  try {
+    // Try primary source
+    return await fetch(primarySource);
+  } catch (primaryError) {
+    logger.warn('Primary source failed, trying fallback', {
+      primarySource,
+      error: primaryError.message,
+    });
+
+    try {
+      // Fallback to secondary source
+      return await fetch(fallbackSource);
+    } catch (fallbackError) {
+      logger.error('Both primary and fallback sources failed', {
+        primaryError: primaryError.message,
+        fallbackError: fallbackError.message,
+      });
+
+      // Return cached data or empty result as last resort
+      return getCachedData() || { data: [], cached: true };
+    }
+  }
+}
+```
+
+### 6. Error Monitoring and Alerting
+
+```typescript
+import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
+
+class ErrorMonitor {
+  private errorCounts = new Map<string, number>();
+  private errorWindow = new Map<string, Date[]>();
+  private readonly windowSize = 5 * 60 * 1000; // 5 minutes
+
+  recordError(error: Error): void {
+    const errorType = error instanceof IngestionError ? error.code : 'UNKNOWN';
+
+    // Increment counter
+    const count = (this.errorCounts.get(errorType) || 0) + 1;
+    this.errorCounts.set(errorType, count);
+
+    // Track in time window
+    const timestamps = this.errorWindow.get(errorType) || [];
+    timestamps.push(new Date());
+    this.errorWindow.set(errorType, timestamps);
+
+    // Clean old entries
+    this.cleanupWindow(errorType);
+
+    // Check for high error rate
+    const recentErrors = this.errorWindow.get(errorType)!.length;
+    if (recentErrors > 10) {
+      this.alertHighErrorRate(errorType, recentErrors);
+    }
+  }
+
+  private cleanupWindow(errorType: string): void {
+    const timestamps = this.errorWindow.get(errorType) || [];
+    const cutoff = Date.now() - this.windowSize;
+    const recent = timestamps.filter(t => t.getTime() > cutoff);
+    this.errorWindow.set(errorType, recent);
+  }
+
+  private alertHighErrorRate(errorType: string, count: number): void {
+    console.error(`ALERT: High error rate detected - ${errorType}: ${count} errors in 5 minutes`);
+    // Send to monitoring system (DataDog, CloudWatch, etc.)
+    // sendAlert({ type: errorType, count, window: '5m' });
+  }
+
+  getMetrics() {
+    return {
+      totalErrors: Object.fromEntries(this.errorCounts),
+      recentErrors: Object.fromEntries(
+        Array.from(this.errorWindow.entries()).map(([type, timestamps]) => [
+          type,
+          timestamps.length,
+        ])
+      ),
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+
+// Usage
+const monitor = new ErrorMonitor();
+
+try {
+  await processFile(fileName);
+} catch (error) {
+  monitor.recordError(error);
+  throw error;
+}
+```
+
+## Best Practices
+
+### Do's
+
+1. **Always Check Error Type**
+
+   ```typescript
+   if (error instanceof IngestionError && error.isRetryable()) {
+     return scheduleRetry();
+   }
+   ```
+
+2. **Use Structured Logging**
+
+   ```typescript
+   logger.error('Operation failed', error.toJSON());
+   ```
+
+3. **Add Context to Errors**
+
+   ```typescript
+   throw new TransformationError('Failed to parse quantity', recordIndex, 'quantity', {
+     record,
+     originalValue,
+   });
+   ```
+
+4. **Re-throw After Handling**
+
+   ```typescript
+   try {
+     await operation();
+   } catch (error) {
+     logger.error('Failed', error);
+     throw error; // Don't swallow errors
+   }
+   ```
+
+5. **Distinguish Retryable Errors**
+   ```typescript
+   // Retryable: NETWORK_ERROR, TIMEOUT_ERROR, RATE_LIMIT_ERROR
+   // Non-retryable: PARSE_ERROR, VALIDATION_ERROR, CONFIGURATION_ERROR
+   ```
+
+### Don'ts
+
+1. **Don't Swallow Errors**
+
+   ```typescript
+   // ❌ WRONG
+   try {
+     await operation();
+   } catch {}
+
+   // ✅ CORRECT
+   try {
+     await operation();
+   } catch (error) {
+     logger.error('Failed', error);
+     throw error;
+   }
+   ```
+
+2. **Don't Retry Non-Retryable Errors**
+
+   ```typescript
+   // ❌ WRONG - Retrying parse errors wastes resources
+   await retry(() => parseXML(invalidXML));
+
+   // ✅ CORRECT - Check if retryable first
+   if (error.isRetryable()) await retry(operation);
+   ```
+
+3. **Don't Use Generic Error Messages**
+
+   ```typescript
+   // ❌ WRONG
+   throw new Error('Failed');
+
+   // ✅ CORRECT
+   throw new FileParsingError('Invalid CSV: missing header row', fileName, 1);
+   ```
+
+4. **Don't Ignore Error Context**
+
+   ```typescript
+   // ❌ WRONG
+   console.log(error.message);
+
+   // ✅ CORRECT
+   console.log(error.toJSON()); // Includes code, context, timestamp, etc.
+   ```
+
+## Retryable vs Non-Retryable Errors
+
+```typescript
+// RETRYABLE - Transient failures
+IngestionErrorCode.NETWORK_ERROR;
+IngestionErrorCode.TIMEOUT_ERROR;
+IngestionErrorCode.RATE_LIMIT_ERROR;
+IngestionErrorCode.LOCK_ACQUISITION_FAILED;
+
+// NON-RETRYABLE - Permanent failures
+IngestionErrorCode.PARSE_ERROR;
+IngestionErrorCode.VALIDATION_ERROR;
+IngestionErrorCode.REQUIRED_FIELD_MISSING;
+IngestionErrorCode.CONFIGURATION_ERROR;
+IngestionErrorCode.FIELD_MAPPING_ERROR;
+IngestionErrorCode.INVALID_FILE_FORMAT;
+```
+
+## Related Patterns
+
+- [Batch Processing Pattern](../../03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-02-batch-processing.md) - Handling batch-level errors
+- [State Management Pattern](../../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-07-state-management.md) - State-related error handling
+- [Configuration Pattern](../../04-REFERENCE/platforms/versori/modules/platforms-versori-02-quick-start.md) - Config validation errors
+
+## Related Documentation
+
+- [Complete Error Handling Guide](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
+- [GraphQL Mapping Error Handling](../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md)
+- [API Reference - Error Classes](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)