@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-08-api-reference.md

@@ -1,847 +1,847 @@
-# Module 8: API Reference
-
-**Level:** Reference
-**Estimated Time:** As needed
-
-## Overview
-
-This module provides complete API documentation for all error classes, error codes, and best practices for error handling in the SDK.
-
-## Error Class Reference
-
-### IngestionError (Base Class)
-
-Base class for all ingestion-related errors.
-
-```typescript
-abstract class IngestionError extends Error {
-  readonly code: IngestionErrorCode;
-  readonly context?: Record<string, any>;
-  readonly timestamp: Date;
-  readonly correlationId?: string;
-
-  constructor(
-    message: string,
-    code: IngestionErrorCode,
-    context?: Record<string, any>,
-    correlationId?: string
-  );
-
-  toJSON(): Record<string, any>;
-  isRetryable(): boolean;
-}
-```
-
-**Properties:**
-- `code`: Machine-readable error code from `IngestionErrorCode` enum
-- `context`: Additional error context (file name, record index, etc.)
-- `timestamp`: When the error occurred
-- `correlationId`: For tracking errors across distributed systems
-- `message`: Human-readable error description
-- `name`: Error class name
-- `stack`: Stack trace
-
-**Methods:**
-
-#### toJSON()
-
-Serializes error to JSON for logging:
-
-```typescript
-const error = new FileParsingError('Invalid XML', 'order.xml', 42);
-const json = error.toJSON();
-// {
-//   name: 'FileParsingError',
-//   message: 'Invalid XML',
-//   code: 'PARSE_ERROR',
-//   fileName: 'order.xml',
-//   lineNumber: 42,
-//   timestamp: '2025-01-10T12:34:56.789Z',
-//   stack: '...'
-// }
-```
-
-#### isRetryable()
-
-Determines if error should be retried:
-
-```typescript
-if (error.isRetryable()) {
-  // Retry with exponential backoff
-  await retryOperation();
-} else {
-  // Permanent failure - don't retry
-  throw error;
-}
-```
-
-**Retryable codes:**
-- `NETWORK_ERROR`
-- `TIMEOUT_ERROR`
-- `RATE_LIMIT_ERROR`
-- `LOCK_ACQUISITION_FAILED`
-
-### FileDiscoveryError
-
-Thrown when file discovery or access fails.
-
-```typescript
-class FileDiscoveryError extends IngestionError {
-  readonly fileName?: string;
-  readonly path?: string;
-}
-```
-
-**Example:**
-
-```typescript
-throw new FileDiscoveryError(
-  'Failed to list S3 bucket',
-  IngestionErrorCode.FILE_DISCOVERY_FAILED,
-  { bucket: 's3://my-bucket', prefix: 'orders/' }
-);
-```
-
-### FileParsingError
-
-Thrown when file parsing fails.
-
-```typescript
-class FileParsingError extends IngestionError {
-  readonly fileName?: string;
-  readonly lineNumber?: number;
-}
-```
-
-**Example:**
-
-```typescript
-throw new FileParsingError(
-  'Unclosed XML tag',
-  'order-123.xml',
-  42,  // line number
-  { tag: 'customer', position: 1234 }
-);
-```
-
-**Common scenarios:**
-- Invalid XML syntax
-- Malformed JSON
-- CSV column mismatch
-- Corrupted Parquet file
-
-### TransformationError
-
-Thrown during data transformation.
-
-```typescript
-class TransformationError extends IngestionError {
-  readonly recordIndex?: number;
-  readonly fieldName?: string;
-}
-```
-
-**Example:**
-
-```typescript
-throw new TransformationError(
-  'Failed to parse date',
-  IngestionErrorCode.TRANSFORMATION_ERROR,
-  {
-    recordIndex: 5,
-    fieldName: 'orderDate',
-    value: 'invalid-date'
-  }
-);
-```
-
-### BatchSubmissionError
-
-Thrown when Batch API submission fails.
-
-```typescript
-class BatchSubmissionError extends IngestionError {
-  readonly jobId?: string;
-  readonly batchId?: string;
-}
-```
-
-**Example:**
-
-```typescript
-throw new BatchSubmissionError(
-  'Batch submission failed',
-  IngestionErrorCode.BATCH_SUBMISSION_ERROR,
-  {
-    jobId: 'JOB-123',
-    batchId: 'BATCH-456',
-    statusCode: 500
-  }
-);
-```
-
-### ConfigurationError
-
-Thrown when SDK configuration is invalid.
-
-```typescript
-class ConfigurationError extends IngestionError {
-  readonly configKey?: string;
-}
-```
-
-**Example:**
-
-```typescript
-throw new ConfigurationError(
-  'Missing required configuration',
-  IngestionErrorCode.MISSING_REQUIRED_CONFIG,
-  { configKey: 'FLUENT_CLIENT_ID' }
-);
-```
-
-### ValidationError
-
-Thrown when data validation fails.
-
-```typescript
-class ValidationError extends IngestionError {
-  readonly validationErrors: Array<{
-    field?: string;
-    value?: any;
-    rule?: string;
-    message: string;
-  }>;
-}
-```
-
-**Example:**
-
-```typescript
-throw new ValidationError(
-  'Validation failed',
-  [
-    {
-      field: 'email',
-      value: 'invalid-email',
-      rule: 'email_format',
-      message: 'Invalid email format'
-    },
-    {
-      field: 'quantity',
-      value: -5,
-      rule: 'min_value',
-      message: 'Quantity must be positive'
-    }
-  ]
-);
-```
-
-### AggregateIngestionError
-
-Thrown when multiple errors occur during batch processing.
-
-```typescript
-class AggregateIngestionError extends IngestionError {
-  readonly errors: IngestionError[];
-
-  getAllCodes(): IngestionErrorCode[];
-  hasRetryableError(): boolean;
-  getErrorsByCode(code: IngestionErrorCode): IngestionError[];
-}
-```
-
-**Example:**
-
-```typescript
-const errors = [
-  new FileParsingError('Invalid XML', 'order-1.xml', 10),
-  new FileParsingError('Invalid XML', 'order-2.xml', 20)
-];
-
-throw new AggregateIngestionError(
-  `${errors.length} files failed processing`,
-  errors,
-  { batchId: 'BATCH-123' }
-);
-
-// Check if any errors are retryable
-if (aggregateError.hasRetryableError()) {
-  // Retry the batch
-}
-```
-
-## New Services for Error Recovery
-
-### PartialBatchRecovery
-
-Service for handling partial batch failures with automatic recovery.
-
-**Purpose:** Retry only failed records instead of entire batches, reducing overhead and improving efficiency.
-
-```typescript
-class PartialBatchRecovery {
-  constructor(logger: Logger);
-
-  async processBatchWithRecovery<T>(
-    records: T[],
-    processFn: (batch: T[]) => Promise<any>,
-    options?: RecoveryOptions
-  ): Promise<RecoveryResult>;
-}
-```
-
-**Options:**
-
-```typescript
-interface RecoveryOptions {
-  maxRetries?: number;              // Max retry attempts per record (default: 3)
-  retryOnlyFailed?: boolean;        // Only retry failed records (default: true)
-  batchSize?: number;               // Batch size for processing (default: 100)
-  retryDelay?: number;              // Delay between retries in ms (default: 1000)
-  exponentialBackoff?: boolean;     // Use exponential backoff (default: true)
-  shouldRetry?: (error: Error, attempt: number) => boolean;
-  calculateDelay?: (attempt: number, baseDelay: number) => number;
-  onProgress?: (current: number, total: number) => void;
-  onRetry?: (record: any, attempt: number, error: Error) => void;
-}
-```
-
-**Return Value:**
-
-```typescript
-interface RecoveryResult {
-  successCount: number;
-  failedCount: number;
-  failedRecords: Array<{
-    record: any;
-    error: Error;
-    attemptCount: number;
-  }>;
-}
-```
-
-**Example:**
-
-```typescript
-import {
-  PartialBatchRecovery,
-  createClient,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Standalone
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'Recovery' });
-
-// Versori
-const { log: logger } = ctx;
-
-const recovery = new PartialBatchRecovery(logger);
-const client = await createClient({ config });
-
-const result = await recovery.processBatchWithRecovery(
-  inventoryRecords,
-  async (batch) => {
-    const job = await client.createJob({ name: 'Sync', retailerId: '1' });
-    return await client.sendBatch(job.id, {
-      action: 'UPSERT',
-      entityType: 'INVENTORY',
-      entities: batch
-    });
-  },
-  {
-    maxRetries: 3,
-    retryOnlyFailed: true,
-    batchSize: 100
-  }
-);
-
-console.log(`Success: ${result.successCount}, Failed: ${result.failedCount}`);
-```
-
-**When to use:**
-- ✅ Large batch imports where some records may fail
-- ✅ Network errors affecting subset of records
-- ✅ Validation failures on specific records
-- ✅ Want to minimize reprocessing overhead
-
-**Benefits:**
-- ✅ Only retries failed records (not entire batch)
-- ✅ Reduces API calls and processing time
-- ✅ Detailed failure reporting with record-level context
-- ✅ Configurable retry logic and backoff strategies
-
-### GraphQLExecutionError
-
-Thrown when GraphQL mutation/query returns errors in response.
-
-```typescript
-class GraphQLExecutionError extends IngestionError {
-  readonly graphqlErrors: Array<{
-    message: string;
-    locations?: Array<{ line: number; column: number }>;
-    path?: Array<string | number>;
-    extensions?: Record<string, any>;
-  }>;
-  readonly query?: string;
-  readonly variables?: Record<string, any>;
-
-  getErrorMessages(): string[];
-  isValidationError(): boolean;
-  isAuthError(): boolean;
-}
-```
-
-**Example:**
-
-```typescript
-try {
-  const result = await client.graphql({ query, variables });
-  if (result.errors) {
-    throw new GraphQLExecutionError(
-      'GraphQL query failed',
-      result.errors,
-      query,
-      variables
-    );
-  }
-} catch (error) {
-  if (error instanceof GraphQLExecutionError) {
-    console.error('GraphQL errors:', error.getErrorMessages());
-
-    if (error.isAuthError()) {
-      logger.error('Authentication failed');
-      // Don't retry
-    } else if (error.isValidationError()) {
-      logger.error('GraphQL validation failed');
-      // Don't retry - fix query/variables
-    }
-  }
-}
-```
-
-**Common scenarios:**
-- GraphQL syntax errors
-- Field permission errors
-- Authentication failures
-- Schema mismatches
-
-### DataSourceError
-
-Thrown when S3 or SFTP data source operations fail.
-
-```typescript
-class DataSourceError extends FluentError {
-  readonly source?: string;
-  readonly operation?: string;
-  readonly details?: Record<string, unknown>;
-}
-```
-
-**Example:**
-
-```typescript
-try {
-  const files = await s3.listFiles({ prefix: 'orders/' });
-} catch (error) {
-  if (error instanceof DataSourceError) {
-    logger.error('S3 operation failed:', {
-      source: error.source,      // 'S3_CSV'
-      operation: error.operation, // 'listFiles'
-      details: error.details      // { bucket, statusCode, etc }
-    });
-
-    // Check if retryable (network/timeout errors)
-    if (error.details?.statusCode === 429 ||
-        error.details?.statusCode === 503) {
-      // Retry with backoff
-    }
-  }
-}
-```
-
-**Common scenarios:**
-- S3 bucket access denied
-- SFTP connection timeout
-- File not found
-- Network errors
-
-**Note:** S3DataSource and SftpDataSource have built-in retry logic, so most transient errors are handled automatically.
-
-### PathResolutionError
-
-Thrown when source path doesn't exist in data.
-
-```typescript
-class PathResolutionError extends Error {
-  readonly path: string;
-  readonly cause?: Error;
-
-  constructor(path: string, cause?: Error);
-}
-```
-
-**Example:**
-
-```typescript
-throw new PathResolutionError(
-  'order.customer.WRONG_PATH.email',
-  new Error('Path not found')
-);
-```
-
-**Note:** Does NOT extend `IngestionError` - always a permanent error.
-
-### MappingError
-
-Thrown when field mapping fails.
-
-```typescript
-class MappingError extends Error {
-  readonly field?: string;
-  readonly sourcePath?: string;
-
-  constructor(
-    message: string,
-    field?: string,
-    sourcePath?: string
-  );
-}
-```
-
-**Example:**
-
-```typescript
-throw new MappingError(
-  "Required field 'ref' is missing or empty",
-  'ref',
-  'order.customerRef'
-);
-```
-
-**Note:** Does NOT extend `IngestionError` - always a permanent error.
-
-### ResolverError
-
-Thrown when a custom resolver fails during field transformation.
-
-```typescript
-class ResolverError extends Error {
-  readonly resolverName: string;
-  readonly fieldName: string;
-  readonly fieldPath: string[];
-  readonly inputValue: unknown;
-  readonly inputValueSnippet?: string;
-  readonly originalError: Error;
-  readonly timestamp: Date;
-
-  toJSON(): Record<string, unknown>;
-}
-```
-
-**Example:**
-
-```typescript
-// Custom resolver that can fail
-const customResolvers = {
-  'custom.parseDate': (value: unknown) => {
-    if (typeof value !== 'string') {
-      throw new Error('Date must be a string');
-    }
-    const date = new Date(value);
-    if (isNaN(date.getTime())) {
-      throw new Error(`Invalid date format: ${value}`);
-    }
-    return date.toISOString();
-  }
-};
-
-try {
-  const mapper = new UniversalMapper(config, { customResolvers });
-  const result = await mapper.map(data);
-} catch (error) {
-  if (error instanceof ResolverError) {
-    logger.error('Resolver transformation failed:', {
-      resolver: error.resolverName,          // 'custom.parseDate'
-      field: error.fieldName,                // 'orderDate'
-      fieldPath: error.fieldPath,            // ['order', 'date']
-      inputValue: error.inputValueSnippet,   // 'invalid-date-string'
-      originalError: error.originalError.message,
-      timestamp: error.timestamp
-    });
-
-    // Don't retry - fix resolver logic or input data
-  }
-}
-```
-
-**Common scenarios:**
-- Date parsing failures in custom resolvers
-- Type conversion errors
-- Custom validation logic failures
-- Transformation exceptions
-
-**Note:** Does NOT extend `IngestionError` - always a permanent error indicating resolver implementation or data issues.
-
-## Error Code Reference
-
-### Complete Error Code Enum
-
-```typescript
-export enum IngestionErrorCode {
-  // File Discovery (20xx)
-  FILE_DISCOVERY_FAILED = 'FILE_DISCOVERY_FAILED',
-  FILE_ACCESS_DENIED = 'FILE_ACCESS_DENIED',
-  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
-  INVALID_FILE_FORMAT = 'INVALID_FILE_FORMAT',
-
-  // Parsing (21xx)
-  PARSE_ERROR = 'PARSE_ERROR',
-  INVALID_CSV_FORMAT = 'INVALID_CSV_FORMAT',
-  INVALID_PARQUET_FORMAT = 'INVALID_PARQUET_FORMAT',
-  ENCODING_ERROR = 'ENCODING_ERROR',
-
-  // Transformation (22xx)
-  TRANSFORMATION_ERROR = 'TRANSFORMATION_ERROR',
-  FIELD_MAPPING_ERROR = 'FIELD_MAPPING_ERROR',
-  VALIDATION_ERROR = 'VALIDATION_ERROR',
-  REQUIRED_FIELD_MISSING = 'REQUIRED_FIELD_MISSING',
-
-  // Submission (23xx)
-  BATCH_SUBMISSION_ERROR = 'BATCH_SUBMISSION_ERROR',
-  JOB_CREATION_ERROR = 'JOB_CREATION_ERROR',
-  API_ERROR = 'API_ERROR',
-  NETWORK_ERROR = 'NETWORK_ERROR',
-
-  // State Management (24xx)
-  LOCK_ACQUISITION_FAILED = 'LOCK_ACQUISITION_FAILED',
-  STATE_UPDATE_FAILED = 'STATE_UPDATE_FAILED',
-
-  // Configuration (25xx)
-  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',
-  MISSING_REQUIRED_CONFIG = 'MISSING_REQUIRED_CONFIG',
-  INVALID_CONFIGURATION = 'INVALID_CONFIGURATION',
-
-  // General (26xx)
-  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
-  TIMEOUT_ERROR = 'TIMEOUT_ERROR',
-  RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',
-}
-```
-
-### Error Code Categories
-
-| Category | Codes | Retryable |
-|----------|-------|-----------|
-| **File Discovery** | `FILE_DISCOVERY_FAILED`, `FILE_ACCESS_DENIED`, `FILE_NOT_FOUND`, `INVALID_FILE_FORMAT` | Depends |
-| **Parsing** | `PARSE_ERROR`, `INVALID_CSV_FORMAT`, `INVALID_PARQUET_FORMAT`, `ENCODING_ERROR` | ❌ No |
-| **Transformation** | `TRANSFORMATION_ERROR`, `FIELD_MAPPING_ERROR`, `VALIDATION_ERROR`, `REQUIRED_FIELD_MISSING` | ❌ No |
-| **Submission** | `BATCH_SUBMISSION_ERROR`, `JOB_CREATION_ERROR`, `API_ERROR`, `NETWORK_ERROR` | ✅ Yes |
-| **State** | `LOCK_ACQUISITION_FAILED` | ✅ Yes |
-| | `STATE_UPDATE_FAILED` | ❌ No |
-| **Configuration** | `CONFIGURATION_ERROR`, `MISSING_REQUIRED_CONFIG`, `INVALID_CONFIGURATION` | ❌ No |
-| **General** | `UNKNOWN_ERROR`, `TIMEOUT_ERROR`, `RATE_LIMIT_ERROR` | ✅ Yes |
-
-## UTF-8 and Special Character Handling
-
-### Automatic BOM Removal
-
-The SDK automatically removes UTF-8 BOM (Byte Order Mark):
-
-```typescript
-// XMLParserService preprocessing
-private preprocessXML(xmlContent: string): string {
-  // Remove BOM (Byte Order Mark) if present
-  let cleaned = xmlContent.replace(/^\uFEFF/, '');
-
-  // Normalize line endings (Windows/Unix/Mac)
-  cleaned = cleaned.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-
-  // Remove XML comments
-  cleaned = cleaned.replace(/<!--[\s\S]*?-->/g, '');
-
-  return cleaned.trim();
-}
-```
-
-### Supported Encodings
-
-- ✅ UTF-8 (standard)
-- ✅ UTF-8 with BOM
-- ✅ Unicode characters (emoji, Chinese, Arabic, accented characters)
-
-### Special Character Escaping
-
-XML special characters are automatically escaped:
-
-```typescript
-private escapeXML(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')     // & → &amp;
-    .replace(/</g, '&lt;')      // < → &lt;
-    .replace(/>/g, '&gt;')      // > → &gt;
-    .replace(/"/g, '&quot;')    // " → &quot;
-    .replace(/'/g, '&apos;');   // ' → &apos;
-}
-```
-
-**Example:**
-
-```xml
-<order>
-  <customer>
-    <name>José García</name>
-    <email>josé@example.com</email>
-    <notes>Special: &amp; &lt; &gt; &quot; 中文 🎉</notes>
-  </customer>
-</order>
-```
-
-## Best Practices
-
-### Error Handling Checklist
-
-- [ ] Wrap all SDK operations in try-catch blocks
-- [ ] Check error types with `instanceof`
-- [ ] Use `error.toJSON()` for structured logging
-- [ ] Check `error.isRetryable()` before retry logic
-- [ ] Re-throw errors after handling (don't silence)
-- [ ] Log with correlation IDs and context
-- [ ] Monitor error rates and patterns
-- [ ] Alert on high error frequencies
-- [ ] Document error scenarios for your team
-- [ ] Test error paths in your code
-
-### Do's and Don'ts
-
-#### ✅ DO
-
-```typescript
-// ✅ Always wrap in try-catch
-try {
-  const result = await mapper.map(data);
-} catch (error) {
-  logger.error('Mapping failed:', error instanceof IngestionError ? error.toJSON() : error);
-  throw error;
-}
-
-// ✅ Check error types
-if (error instanceof MappingError) {
-  logger.error('Mapping error:', { field: error.field, path: error.sourcePath });
-}
-
-// ✅ Use isRetryable()
-if (error instanceof IngestionError && error.isRetryable()) {
-  return scheduleRetry();
-}
-
-// ✅ Log with context
-logger.error('Processing failed', {
-  error: error.toJSON(),
-  orderId,
-  fileName,
-  correlationId
-});
-```
-
-#### ❌ DON'T
-
-```typescript
-// ❌ Don't silence errors
-try {
-  await processOrder(data);
-} catch (error) {
-  // Do nothing - ERROR IS LOST!
-}
-
-// ❌ Don't retry permanent errors
-if (error instanceof FileParsingError) {
-  await retryOperation();  // Won't succeed!
-}
-
-// ❌ Don't log without context
-logger.error('Error occurred');
-
-// ❌ Don't throw strings
-throw 'Something went wrong';  // Use Error objects!
-```
-
-### Error Context Best Practices
-
-Always include these in error logs:
-
-1. **Timestamp** - When error occurred
-2. **Correlation ID** - Track across systems
-3. **Business context** - Order ID, customer ID, etc.
-4. **Operation** - What was being attempted
-5. **Attempt** - Retry attempt number
-6. **Environment** - Dev, staging, production
-7. **Version** - Application version
-
-```typescript
-logger.error('Order processing failed', {
-  timestamp: new Date().toISOString(),
-  correlationId: context.correlationId,
-  orderId: metadata.orderId,
-  customerId: metadata.customerId,
-  operation: 'processOrder',
-  attempt: retryAttempt,
-  environment: process.env.NODE_ENV,
-  version: process.env.APP_VERSION,
-  error: error instanceof IngestionError ? error.toJSON() : error.message
-});
-```
-
-## Summary
-
-### Key Concepts
-
-1. **Fail-Fast** - One error stops everything, no partial data
-2. **Error Hierarchy** - All ingestion errors extend `IngestionError`
-3. **Error Codes** - Machine-readable codes for programmatic handling
-4. **Retryability** - Use `isRetryable()` to determine retry strategy
-5. **Structured Logging** - Use `toJSON()` for complete error data
-6. **UTF-8 Support** - Automatic BOM removal and special character handling
-
-### Quick Reference Table
-
-| Error Class | When Thrown | Retryable | Key Properties |
-|-------------|-------------|-----------|----------------|
-| `FileParsingError` | XML/CSV/JSON parsing fails | ❌ No | `fileName`, `lineNumber` |
-| `PathResolutionError` | Path doesn't exist in data | ❌ No | `path` |
-| `MappingError` | Field mapping fails | ❌ No | `field`, `sourcePath` |
-| `ResolverError` | Resolver transformation fails | ❌ No | `resolverName`, `fieldName`, `fieldPath`, `originalError` |
-| `ValidationError` | Data validation fails | ❌ No | `validationErrors[]` |
-| `ConfigurationError` | Invalid config | ❌ No | `configKey` |
-| `FluentAPIError` | HTTP error (4xx/5xx) | ✅ Yes (5xx) | `statusCode`, `details` |
-| `AuthenticationError` | Auth failed (after retries) | ❌ No | `statusCode` (401) |
-| `BatchSubmissionError` | API submission fails | ✅ Yes | `jobId`, `batchId` |
-| `GraphQLExecutionError` | GraphQL errors in response | ❌ No* | `graphqlErrors[]`, `query`, `variables` |
-| `DataSourceError` | S3/SFTP operation fails | Depends† | `source`, `operation`, `details` |
-| `IngestionError` (base) | Various ingestion issues | Depends | `code`, `context` |
-
-**Notes:**
-- *GraphQLExecutionError: Not retryable unless due to network issues (check extensions)
-- †DataSourceError: Retryable if network/timeout error; S3/SFTP have built-in retry (v0.1.10+)
-
-### Related Documentation
-
-- [Module 1: Foundations](./error-handling-01-foundations.md) - Fail-fast principles
-- [Module 2: Error Types](./error-handling-02-error-types.md) - Error class hierarchy
-- [Module 3: UTF-8 Handling](./error-handling-03-utf8-handling.md) - UTF-8 encoding
-- [Module 4: Error Scenarios](./error-handling-04-error-scenarios.md) - Real-world examples
-- [Module 5: Calling Patterns](./error-handling-05-calling-patterns.md) - Code patterns
-- [Module 6: Retry Strategies](./error-handling-06-retry-strategies.md) - Retry logic
-- [Module 7: Monitoring](./error-handling-07-monitoring.md) - Logging best practices
-
-## Need Help?
-
-- 📖 Browse [Examples](../examples/)
-- 🔍 Check [Error Scenarios](./error-handling-04-error-scenarios.md)
-- 📋 Review [Quick Reference](../../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md)
-- 🐛 Report issues at [GitHub](https://github.com/fluentcommerce/fc-connect-sdk/issues)
-
----
-
-**Previous:** [← Module 7: Monitoring](./error-handling-07-monitoring.md)
+# Module 8: API Reference
+
+**Level:** Reference
+**Estimated Time:** As needed
+
+## Overview
+
+This module provides complete API documentation for all error classes, error codes, and best practices for error handling in the SDK.
+
+## Error Class Reference
+
+### IngestionError (Base Class)
+
+Base class for all ingestion-related errors.
+
+```typescript
+abstract class IngestionError extends Error {
+  readonly code: IngestionErrorCode;
+  readonly context?: Record<string, any>;
+  readonly timestamp: Date;
+  readonly correlationId?: string;
+
+  constructor(
+    message: string,
+    code: IngestionErrorCode,
+    context?: Record<string, any>,
+    correlationId?: string
+  );
+
+  toJSON(): Record<string, any>;
+  isRetryable(): boolean;
+}
+```
+
+**Properties:**
+- `code`: Machine-readable error code from `IngestionErrorCode` enum
+- `context`: Additional error context (file name, record index, etc.)
+- `timestamp`: When the error occurred
+- `correlationId`: For tracking errors across distributed systems
+- `message`: Human-readable error description
+- `name`: Error class name
+- `stack`: Stack trace
+
+**Methods:**
+
+#### toJSON()
+
+Serializes error to JSON for logging:
+
+```typescript
+const error = new FileParsingError('Invalid XML', 'order.xml', 42);
+const json = error.toJSON();
+// {
+//   name: 'FileParsingError',
+//   message: 'Invalid XML',
+//   code: 'PARSE_ERROR',
+//   fileName: 'order.xml',
+//   lineNumber: 42,
+//   timestamp: '2025-01-10T12:34:56.789Z',
+//   stack: '...'
+// }
+```
+
+#### isRetryable()
+
+Determines if error should be retried:
+
+```typescript
+if (error.isRetryable()) {
+  // Retry with exponential backoff
+  await retryOperation();
+} else {
+  // Permanent failure - don't retry
+  throw error;
+}
+```
+
+**Retryable codes:**
+- `NETWORK_ERROR`
+- `TIMEOUT_ERROR`
+- `RATE_LIMIT_ERROR`
+- `LOCK_ACQUISITION_FAILED`
+
+### FileDiscoveryError
+
+Thrown when file discovery or access fails.
+
+```typescript
+class FileDiscoveryError extends IngestionError {
+  readonly fileName?: string;
+  readonly path?: string;
+}
+```
+
+**Example:**
+
+```typescript
+throw new FileDiscoveryError(
+  'Failed to list S3 bucket',
+  IngestionErrorCode.FILE_DISCOVERY_FAILED,
+  { bucket: 's3://my-bucket', prefix: 'orders/' }
+);
+```
+
+### FileParsingError
+
+Thrown when file parsing fails.
+
+```typescript
+class FileParsingError extends IngestionError {
+  readonly fileName?: string;
+  readonly lineNumber?: number;
+}
+```
+
+**Example:**
+
+```typescript
+throw new FileParsingError(
+  'Unclosed XML tag',
+  'order-123.xml',
+  42,  // line number
+  { tag: 'customer', position: 1234 }
+);
+```
+
+**Common scenarios:**
+- Invalid XML syntax
+- Malformed JSON
+- CSV column mismatch
+- Corrupted Parquet file
+
+### TransformationError
+
+Thrown during data transformation.
+
+```typescript
+class TransformationError extends IngestionError {
+  readonly recordIndex?: number;
+  readonly fieldName?: string;
+}
+```
+
+**Example:**
+
+```typescript
+throw new TransformationError(
+  'Failed to parse date',
+  IngestionErrorCode.TRANSFORMATION_ERROR,
+  {
+    recordIndex: 5,
+    fieldName: 'orderDate',
+    value: 'invalid-date'
+  }
+);
+```
+
+### BatchSubmissionError
+
+Thrown when Batch API submission fails.
+
+```typescript
+class BatchSubmissionError extends IngestionError {
+  readonly jobId?: string;
+  readonly batchId?: string;
+}
+```
+
+**Example:**
+
+```typescript
+throw new BatchSubmissionError(
+  'Batch submission failed',
+  IngestionErrorCode.BATCH_SUBMISSION_ERROR,
+  {
+    jobId: 'JOB-123',
+    batchId: 'BATCH-456',
+    statusCode: 500
+  }
+);
+```
+
+### ConfigurationError
+
+Thrown when SDK configuration is invalid.
+
+```typescript
+class ConfigurationError extends IngestionError {
+  readonly configKey?: string;
+}
+```
+
+**Example:**
+
+```typescript
+throw new ConfigurationError(
+  'Missing required configuration',
+  IngestionErrorCode.MISSING_REQUIRED_CONFIG,
+  { configKey: 'FLUENT_CLIENT_ID' }
+);
+```
+
+### ValidationError
+
+Thrown when data validation fails.
+
+```typescript
+class ValidationError extends IngestionError {
+  readonly validationErrors: Array<{
+    field?: string;
+    value?: any;
+    rule?: string;
+    message: string;
+  }>;
+}
+```
+
+**Example:**
+
+```typescript
+throw new ValidationError(
+  'Validation failed',
+  [
+    {
+      field: 'email',
+      value: 'invalid-email',
+      rule: 'email_format',
+      message: 'Invalid email format'
+    },
+    {
+      field: 'quantity',
+      value: -5,
+      rule: 'min_value',
+      message: 'Quantity must be positive'
+    }
+  ]
+);
+```
+
+### AggregateIngestionError
+
+Thrown when multiple errors occur during batch processing.
+
+```typescript
+class AggregateIngestionError extends IngestionError {
+  readonly errors: IngestionError[];
+
+  getAllCodes(): IngestionErrorCode[];
+  hasRetryableError(): boolean;
+  getErrorsByCode(code: IngestionErrorCode): IngestionError[];
+}
+```
+
+**Example:**
+
+```typescript
+const errors = [
+  new FileParsingError('Invalid XML', 'order-1.xml', 10),
+  new FileParsingError('Invalid XML', 'order-2.xml', 20)
+];
+
+throw new AggregateIngestionError(
+  `${errors.length} files failed processing`,
+  errors,
+  { batchId: 'BATCH-123' }
+);
+
+// Check if any errors are retryable
+if (aggregateError.hasRetryableError()) {
+  // Retry the batch
+}
+```
+
+## New Services for Error Recovery
+
+### PartialBatchRecovery
+
+Service for handling partial batch failures with automatic recovery.
+
+**Purpose:** Retry only failed records instead of entire batches, reducing overhead and improving efficiency.
+
+```typescript
+class PartialBatchRecovery {
+  constructor(logger: Logger);
+
+  async processBatchWithRecovery<T>(
+    records: T[],
+    processFn: (batch: T[]) => Promise<any>,
+    options?: RecoveryOptions
+  ): Promise<RecoveryResult>;
+}
+```
+
+**Options:**
+
+```typescript
+interface RecoveryOptions {
+  maxRetries?: number;              // Max retry attempts per record (default: 3)
+  retryOnlyFailed?: boolean;        // Only retry failed records (default: true)
+  batchSize?: number;               // Batch size for processing (default: 100)
+  retryDelay?: number;              // Delay between retries in ms (default: 1000)
+  exponentialBackoff?: boolean;     // Use exponential backoff (default: true)
+  shouldRetry?: (error: Error, attempt: number) => boolean;
+  calculateDelay?: (attempt: number, baseDelay: number) => number;
+  onProgress?: (current: number, total: number) => void;
+  onRetry?: (record: any, attempt: number, error: Error) => void;
+}
+```
+
+**Return Value:**
+
+```typescript
+interface RecoveryResult {
+  successCount: number;
+  failedCount: number;
+  failedRecords: Array<{
+    record: any;
+    error: Error;
+    attemptCount: number;
+  }>;
+}
+```
+
+**Example:**
+
+```typescript
+import {
+  PartialBatchRecovery,
+  createClient,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Standalone
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'Recovery' });
+
+// Versori
+const { log: logger } = ctx;
+
+const recovery = new PartialBatchRecovery(logger);
+const client = await createClient({ config });
+
+const result = await recovery.processBatchWithRecovery(
+  inventoryRecords,
+  async (batch) => {
+    const job = await client.createJob({ name: 'Sync', retailerId: '1' });
+    return await client.sendBatch(job.id, {
+      action: 'UPSERT',
+      entityType: 'INVENTORY',
+      entities: batch
+    });
+  },
+  {
+    maxRetries: 3,
+    retryOnlyFailed: true,
+    batchSize: 100
+  }
+);
+
+console.log(`Success: ${result.successCount}, Failed: ${result.failedCount}`);
+```
+
+**When to use:**
+- ✅ Large batch imports where some records may fail
+- ✅ Network errors affecting subset of records
+- ✅ Validation failures on specific records
+- ✅ Want to minimize reprocessing overhead
+
+**Benefits:**
+- ✅ Only retries failed records (not entire batch)
+- ✅ Reduces API calls and processing time
+- ✅ Detailed failure reporting with record-level context
+- ✅ Configurable retry logic and backoff strategies
+
+### GraphQLExecutionError
+
+Thrown when GraphQL mutation/query returns errors in response.
+
+```typescript
+class GraphQLExecutionError extends IngestionError {
+  readonly graphqlErrors: Array<{
+    message: string;
+    locations?: Array<{ line: number; column: number }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, any>;
+  }>;
+  readonly query?: string;
+  readonly variables?: Record<string, any>;
+
+  getErrorMessages(): string[];
+  isValidationError(): boolean;
+  isAuthError(): boolean;
+}
+```
+
+**Example:**
+
+```typescript
+try {
+  const result = await client.graphql({ query, variables });
+  if (result.errors) {
+    throw new GraphQLExecutionError(
+      'GraphQL query failed',
+      result.errors,
+      query,
+      variables
+    );
+  }
+} catch (error) {
+  if (error instanceof GraphQLExecutionError) {
+    console.error('GraphQL errors:', error.getErrorMessages());
+
+    if (error.isAuthError()) {
+      logger.error('Authentication failed');
+      // Don't retry
+    } else if (error.isValidationError()) {
+      logger.error('GraphQL validation failed');
+      // Don't retry - fix query/variables
+    }
+  }
+}
+```
+
+**Common scenarios:**
+- GraphQL syntax errors
+- Field permission errors
+- Authentication failures
+- Schema mismatches
+
+### DataSourceError
+
+Thrown when S3 or SFTP data source operations fail.
+
+```typescript
+class DataSourceError extends FluentError {
+  readonly source?: string;
+  readonly operation?: string;
+  readonly details?: Record<string, unknown>;
+}
+```
+
+**Example:**
+
+```typescript
+try {
+  const files = await s3.listFiles({ prefix: 'orders/' });
+} catch (error) {
+  if (error instanceof DataSourceError) {
+    logger.error('S3 operation failed:', {
+      source: error.source,      // 'S3_CSV'
+      operation: error.operation, // 'listFiles'
+      details: error.details      // { bucket, statusCode, etc }
+    });
+
+    // Check if retryable (network/timeout errors)
+    if (error.details?.statusCode === 429 ||
+        error.details?.statusCode === 503) {
+      // Retry with backoff
+    }
+  }
+}
+```
+
+**Common scenarios:**
+- S3 bucket access denied
+- SFTP connection timeout
+- File not found
+- Network errors
+
+**Note:** S3DataSource and SftpDataSource have built-in retry logic, so most transient errors are handled automatically.
+
+### PathResolutionError
+
+Thrown when source path doesn't exist in data.
+
+```typescript
+class PathResolutionError extends Error {
+  readonly path: string;
+  readonly cause?: Error;
+
+  constructor(path: string, cause?: Error);
+}
+```
+
+**Example:**
+
+```typescript
+throw new PathResolutionError(
+  'order.customer.WRONG_PATH.email',
+  new Error('Path not found')
+);
+```
+
+**Note:** Does NOT extend `IngestionError` - always a permanent error.
+
+### MappingError
+
+Thrown when field mapping fails.
+
+```typescript
+class MappingError extends Error {
+  readonly field?: string;
+  readonly sourcePath?: string;
+
+  constructor(
+    message: string,
+    field?: string,
+    sourcePath?: string
+  );
+}
+```
+
+**Example:**
+
+```typescript
+throw new MappingError(
+  "Required field 'ref' is missing or empty",
+  'ref',
+  'order.customerRef'
+);
+```
+
+**Note:** Does NOT extend `IngestionError` - always a permanent error.
+
+### ResolverError
+
+Thrown when a custom resolver fails during field transformation.
+
+```typescript
+class ResolverError extends Error {
+  readonly resolverName: string;
+  readonly fieldName: string;
+  readonly fieldPath: string[];
+  readonly inputValue: unknown;
+  readonly inputValueSnippet?: string;
+  readonly originalError: Error;
+  readonly timestamp: Date;
+
+  toJSON(): Record<string, unknown>;
+}
+```
+
+**Example:**
+
+```typescript
+// Custom resolver that can fail
+const customResolvers = {
+  'custom.parseDate': (value: unknown) => {
+    if (typeof value !== 'string') {
+      throw new Error('Date must be a string');
+    }
+    const date = new Date(value);
+    if (isNaN(date.getTime())) {
+      throw new Error(`Invalid date format: ${value}`);
+    }
+    return date.toISOString();
+  }
+};
+
+try {
+  const mapper = new UniversalMapper(config, { customResolvers });
+  const result = await mapper.map(data);
+} catch (error) {
+  if (error instanceof ResolverError) {
+    logger.error('Resolver transformation failed:', {
+      resolver: error.resolverName,          // 'custom.parseDate'
+      field: error.fieldName,                // 'orderDate'
+      fieldPath: error.fieldPath,            // ['order', 'date']
+      inputValue: error.inputValueSnippet,   // 'invalid-date-string'
+      originalError: error.originalError.message,
+      timestamp: error.timestamp
+    });
+
+    // Don't retry - fix resolver logic or input data
+  }
+}
+```
+
+**Common scenarios:**
+- Date parsing failures in custom resolvers
+- Type conversion errors
+- Custom validation logic failures
+- Transformation exceptions
+
+**Note:** Does NOT extend `IngestionError` - always a permanent error indicating resolver implementation or data issues.
+
+## Error Code Reference
+
+### Complete Error Code Enum
+
+```typescript
+export enum IngestionErrorCode {
+  // File Discovery (20xx)
+  FILE_DISCOVERY_FAILED = 'FILE_DISCOVERY_FAILED',
+  FILE_ACCESS_DENIED = 'FILE_ACCESS_DENIED',
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  INVALID_FILE_FORMAT = 'INVALID_FILE_FORMAT',
+
+  // Parsing (21xx)
+  PARSE_ERROR = 'PARSE_ERROR',
+  INVALID_CSV_FORMAT = 'INVALID_CSV_FORMAT',
+  INVALID_PARQUET_FORMAT = 'INVALID_PARQUET_FORMAT',
+  ENCODING_ERROR = 'ENCODING_ERROR',
+
+  // Transformation (22xx)
+  TRANSFORMATION_ERROR = 'TRANSFORMATION_ERROR',
+  FIELD_MAPPING_ERROR = 'FIELD_MAPPING_ERROR',
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  REQUIRED_FIELD_MISSING = 'REQUIRED_FIELD_MISSING',
+
+  // Submission (23xx)
+  BATCH_SUBMISSION_ERROR = 'BATCH_SUBMISSION_ERROR',
+  JOB_CREATION_ERROR = 'JOB_CREATION_ERROR',
+  API_ERROR = 'API_ERROR',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+
+  // State Management (24xx)
+  LOCK_ACQUISITION_FAILED = 'LOCK_ACQUISITION_FAILED',
+  STATE_UPDATE_FAILED = 'STATE_UPDATE_FAILED',
+
+  // Configuration (25xx)
+  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',
+  MISSING_REQUIRED_CONFIG = 'MISSING_REQUIRED_CONFIG',
+  INVALID_CONFIGURATION = 'INVALID_CONFIGURATION',
+
+  // General (26xx)
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+  TIMEOUT_ERROR = 'TIMEOUT_ERROR',
+  RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',
+}
+```
+
+### Error Code Categories
+
+| Category | Codes | Retryable |
+|----------|-------|-----------|
+| **File Discovery** | `FILE_DISCOVERY_FAILED`, `FILE_ACCESS_DENIED`, `FILE_NOT_FOUND`, `INVALID_FILE_FORMAT` | Depends |
+| **Parsing** | `PARSE_ERROR`, `INVALID_CSV_FORMAT`, `INVALID_PARQUET_FORMAT`, `ENCODING_ERROR` | ❌ No |
+| **Transformation** | `TRANSFORMATION_ERROR`, `FIELD_MAPPING_ERROR`, `VALIDATION_ERROR`, `REQUIRED_FIELD_MISSING` | ❌ No |
+| **Submission** | `BATCH_SUBMISSION_ERROR`, `JOB_CREATION_ERROR`, `API_ERROR`, `NETWORK_ERROR` | ✅ Yes |
+| **State** | `LOCK_ACQUISITION_FAILED` | ✅ Yes |
+| | `STATE_UPDATE_FAILED` | ❌ No |
+| **Configuration** | `CONFIGURATION_ERROR`, `MISSING_REQUIRED_CONFIG`, `INVALID_CONFIGURATION` | ❌ No |
+| **General** | `UNKNOWN_ERROR`, `TIMEOUT_ERROR`, `RATE_LIMIT_ERROR` | ✅ Yes |
+
+## UTF-8 and Special Character Handling
+
+### Automatic BOM Removal
+
+The SDK automatically removes UTF-8 BOM (Byte Order Mark):
+
+```typescript
+// XMLParserService preprocessing
+private preprocessXML(xmlContent: string): string {
+  // Remove BOM (Byte Order Mark) if present
+  let cleaned = xmlContent.replace(/^\uFEFF/, '');
+
+  // Normalize line endings (Windows/Unix/Mac)
+  cleaned = cleaned.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+  // Remove XML comments
+  cleaned = cleaned.replace(/<!--[\s\S]*?-->/g, '');
+
+  return cleaned.trim();
+}
+```
+
+### Supported Encodings
+
+- ✅ UTF-8 (standard)
+- ✅ UTF-8 with BOM
+- ✅ Unicode characters (emoji, Chinese, Arabic, accented characters)
+
+### Special Character Escaping
+
+XML special characters are automatically escaped:
+
+```typescript
+private escapeXML(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')     // & → &amp;
+    .replace(/</g, '&lt;')      // < → &lt;
+    .replace(/>/g, '&gt;')      // > → &gt;
+    .replace(/"/g, '&quot;')    // " → &quot;
+    .replace(/'/g, '&apos;');   // ' → &apos;
+}
+```
+
+**Example:**
+
+```xml
+<order>
+  <customer>
+    <name>José García</name>
+    <email>josé@example.com</email>
+    <notes>Special: &amp; &lt; &gt; &quot; 中文 🎉</notes>
+  </customer>
+</order>
+```
+
+## Best Practices
+
+### Error Handling Checklist
+
+- [ ] Wrap all SDK operations in try-catch blocks
+- [ ] Check error types with `instanceof`
+- [ ] Use `error.toJSON()` for structured logging
+- [ ] Check `error.isRetryable()` before retry logic
+- [ ] Re-throw errors after handling (don't silence)
+- [ ] Log with correlation IDs and context
+- [ ] Monitor error rates and patterns
+- [ ] Alert on high error frequencies
+- [ ] Document error scenarios for your team
+- [ ] Test error paths in your code
+
+### Do's and Don'ts
+
+#### ✅ DO
+
+```typescript
+// ✅ Always wrap in try-catch
+try {
+  const result = await mapper.map(data);
+} catch (error) {
+  logger.error('Mapping failed:', error instanceof IngestionError ? error.toJSON() : error);
+  throw error;
+}
+
+// ✅ Check error types
+if (error instanceof MappingError) {
+  logger.error('Mapping error:', { field: error.field, path: error.sourcePath });
+}
+
+// ✅ Use isRetryable()
+if (error instanceof IngestionError && error.isRetryable()) {
+  return scheduleRetry();
+}
+
+// ✅ Log with context
+logger.error('Processing failed', {
+  error: error.toJSON(),
+  orderId,
+  fileName,
+  correlationId
+});
+```
+
+#### ❌ DON'T
+
+```typescript
+// ❌ Don't silence errors
+try {
+  await processOrder(data);
+} catch (error) {
+  // Do nothing - ERROR IS LOST!
+}
+
+// ❌ Don't retry permanent errors
+if (error instanceof FileParsingError) {
+  await retryOperation();  // Won't succeed!
+}
+
+// ❌ Don't log without context
+logger.error('Error occurred');
+
+// ❌ Don't throw strings
+throw 'Something went wrong';  // Use Error objects!
+```
+
+### Error Context Best Practices
+
+Always include these in error logs:
+
+1. **Timestamp** - When error occurred
+2. **Correlation ID** - Track across systems
+3. **Business context** - Order ID, customer ID, etc.
+4. **Operation** - What was being attempted
+5. **Attempt** - Retry attempt number
+6. **Environment** - Dev, staging, production
+7. **Version** - Application version
+
+```typescript
+logger.error('Order processing failed', {
+  timestamp: new Date().toISOString(),
+  correlationId: context.correlationId,
+  orderId: metadata.orderId,
+  customerId: metadata.customerId,
+  operation: 'processOrder',
+  attempt: retryAttempt,
+  environment: process.env.NODE_ENV,
+  version: process.env.APP_VERSION,
+  error: error instanceof IngestionError ? error.toJSON() : error.message
+});
+```
+
+## Summary
+
+### Key Concepts
+
+1. **Fail-Fast** - One error stops everything, no partial data
+2. **Error Hierarchy** - All ingestion errors extend `IngestionError`
+3. **Error Codes** - Machine-readable codes for programmatic handling
+4. **Retryability** - Use `isRetryable()` to determine retry strategy
+5. **Structured Logging** - Use `toJSON()` for complete error data
+6. **UTF-8 Support** - Automatic BOM removal and special character handling
+
+### Quick Reference Table
+
+| Error Class | When Thrown | Retryable | Key Properties |
+|-------------|-------------|-----------|----------------|
+| `FileParsingError` | XML/CSV/JSON parsing fails | ❌ No | `fileName`, `lineNumber` |
+| `PathResolutionError` | Path doesn't exist in data | ❌ No | `path` |
+| `MappingError` | Field mapping fails | ❌ No | `field`, `sourcePath` |
+| `ResolverError` | Resolver transformation fails | ❌ No | `resolverName`, `fieldName`, `fieldPath`, `originalError` |
+| `ValidationError` | Data validation fails | ❌ No | `validationErrors[]` |
+| `ConfigurationError` | Invalid config | ❌ No | `configKey` |
+| `FluentAPIError` | HTTP error (4xx/5xx) | ✅ Yes (5xx) | `statusCode`, `details` |
+| `AuthenticationError` | Auth failed (after retries) | ❌ No | `statusCode` (401) |
+| `BatchSubmissionError` | API submission fails | ✅ Yes | `jobId`, `batchId` |
+| `GraphQLExecutionError` | GraphQL errors in response | ❌ No* | `graphqlErrors[]`, `query`, `variables` |
+| `DataSourceError` | S3/SFTP operation fails | Depends† | `source`, `operation`, `details` |
+| `IngestionError` (base) | Various ingestion issues | Depends | `code`, `context` |
+
+**Notes:**
+- *GraphQLExecutionError: Not retryable unless due to network issues (check extensions)
+- †DataSourceError: Retryable if network/timeout error; S3/SFTP have built-in retry (v0.1.10+)
+
+### Related Documentation
+
+- [Module 1: Foundations](./error-handling-01-foundations.md) - Fail-fast principles
+- [Module 2: Error Types](./error-handling-02-error-types.md) - Error class hierarchy
+- [Module 3: UTF-8 Handling](./error-handling-03-utf8-handling.md) - UTF-8 encoding
+- [Module 4: Error Scenarios](./error-handling-04-error-scenarios.md) - Real-world examples
+- [Module 5: Calling Patterns](./error-handling-05-calling-patterns.md) - Code patterns
+- [Module 6: Retry Strategies](./error-handling-06-retry-strategies.md) - Retry logic
+- [Module 7: Monitoring](./error-handling-07-monitoring.md) - Logging best practices
+
+## Need Help?
+
+- 📖 Browse [Examples](../examples/)
+- 🔍 Check [Error Scenarios](./error-handling-04-error-scenarios.md)
+- 📋 Review [Quick Reference](../../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md)
+- 🐛 Report issues at [GitHub](https://github.com/fluentcommerce/fc-connect-sdk/issues)
+
+---
+
+**Previous:** [← Module 7: Monitoring](./error-handling-07-monitoring.md)