@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-02-error-types.md

@@ -1,850 +1,850 @@
-# Module 2: Error Types & Codes
-
-**Level:** Beginner
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module provides a complete reference to all error types and error codes in the SDK, including the error class hierarchy and when each error is thrown.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand the error class hierarchy
-- ✅ Know all available error codes and their meanings
-- ✅ Recognize which error class is thrown for each scenario
-- ✅ Use `instanceof` checks to handle specific error types
-
-## Error Class Hierarchy
-
-```
-Error (JavaScript base class)
-  │
-  ├── IngestionError (Ingestion base class)
-  │     ├── FileDiscoveryError
-  │     ├── FileParsingError
-  │     ├── TransformationError
-  │     ├── BatchSubmissionError
-  │     ├── ConfigurationError
-  │     ├── ValidationError
-  │     ├── GraphQLExecutionError
-  │     └── AggregateIngestionError
-  │
-  ├── FluentError (Base SDK error class - used by services)
-  │     ├── FluentAPIError (HTTP errors from Fluent API)
-  │     ├── AuthenticationError (401 Unauthorized)
-  │     ├── FluentValidationError (Client-side validation)
-  │     ├── DataSourceError (S3/SFTP data source errors)
-  │     └── WebhookValidationError (Webhook signature validation errors)
-  │
-  ├── MappingError (Field mapping errors - standalone)
-  │
-  ├── ResolverError (Resolver transformation errors - standalone)
-  │
-  └── PathResolutionError (Path resolution errors - standalone)
-```
-
-**Key Points:**
-- `IngestionError` is the base class for all ingestion-related errors
-- `PathResolutionError`, `MappingError`, and `ResolverError` do NOT extend `IngestionError` - they are standalone error classes
-- `FluentError` is used by SDK services (S3, SFTP, webhooks) - separate from ingestion errors
-
-### Base Classes
-
-#### IngestionError (SDK Base)
-
-The base class for all ingestion-related errors:
-
-```typescript
-class IngestionError extends Error {
-  readonly code: IngestionErrorCode;
-  readonly context?: Record<string, any>;
-  readonly timestamp: Date;
-  readonly correlationId?: string;
-
-  toJSON(): Record<string, any>;
-  isRetryable(): boolean;
-}
-```
-
-**Key features:**
-- `code`: Machine-readable error code for programmatic handling
-- `context`: Additional error context (file name, record index, etc.)
-- `timestamp`: When the error occurred
-- `correlationId`: For tracking errors across distributed systems
-- `toJSON()`: Serialize error for logging/monitoring
-- `isRetryable()`: Check if error should be retried
-
-**Usage:**
-
-```typescript
-try {
-  await processFile(fileName);
-} catch (error) {
-  if (error instanceof IngestionError) {
-    console.log('Error code:', error.code);
-    console.log('Error JSON:', error.toJSON());
-    console.log('Can retry?', error.isRetryable());
-  }
-}
-```
-
-## Error Codes Reference
-
-### File Discovery Errors (20xx)
-
-Errors that occur when discovering or accessing files:
-
-```typescript
-export enum IngestionErrorCode {
-  FILE_DISCOVERY_FAILED = 'FILE_DISCOVERY_FAILED',  // Failed to discover files
-  FILE_ACCESS_DENIED = 'FILE_ACCESS_DENIED',        // Permission denied
-  FILE_NOT_FOUND = 'FILE_NOT_FOUND',                // File doesn't exist
-  INVALID_FILE_FORMAT = 'INVALID_FILE_FORMAT',      // Unsupported file type
-}
-```
-
-**When thrown:**
-- Listing S3 bucket fails
-- SFTP connection fails
-- File permissions insufficient
-- File path doesn't exist
-
-**Retryable:** Usually Yes (network issues)
-
-### Parsing Errors (21xx)
-
-Errors during file content parsing:
-
-```typescript
-export enum IngestionErrorCode {
-  PARSE_ERROR = 'PARSE_ERROR',                      // Generic parsing error
-  INVALID_CSV_FORMAT = 'INVALID_CSV_FORMAT',        // Malformed CSV
-  INVALID_PARQUET_FORMAT = 'INVALID_PARQUET_FORMAT', // Invalid Parquet file
-  ENCODING_ERROR = 'ENCODING_ERROR',                // Character encoding issue
-}
-```
-
-**When thrown:**
-- XML is malformed (missing closing tag)
-- JSON is invalid (syntax error)
-- CSV has inconsistent columns
-- Parquet file is corrupted
-- Character encoding is not UTF-8
-
-**Retryable:** No (source data issue)
-
-### Transformation Errors (22xx)
-
-Errors during field mapping and transformation:
-
-```typescript
-export enum IngestionErrorCode {
-  TRANSFORMATION_ERROR = 'TRANSFORMATION_ERROR',    // Generic transformation error
-  FIELD_MAPPING_ERROR = 'FIELD_MAPPING_ERROR',      // Field mapping failed
-  VALIDATION_ERROR = 'VALIDATION_ERROR',            // Data validation failed
-  REQUIRED_FIELD_MISSING = 'REQUIRED_FIELD_MISSING', // Required field empty
-}
-```
-
-**When thrown:**
-- Required field is missing or empty
-- Field type mismatch (expected number, got string)
-- Array validation failed (minItems, maxItems)
-- Custom resolver threw error
-- Source path doesn't exist in data
-
-**Retryable:** No (data or configuration issue)
-
-### Submission Errors (23xx)
-
-Errors when submitting to Fluent API:
-
-```typescript
-export enum IngestionErrorCode {
-  BATCH_SUBMISSION_ERROR = 'BATCH_SUBMISSION_ERROR', // Batch API error
-  JOB_CREATION_ERROR = 'JOB_CREATION_ERROR',        // Job creation failed
-  API_ERROR = 'API_ERROR',                          // Fluent API error
-  NETWORK_ERROR = 'NETWORK_ERROR',                  // Network connectivity
-}
-```
-
-**When thrown:**
-- Batch API returns error response
-- Job creation fails
-- Network timeout
-- API endpoint unreachable
-
-**Retryable:** Usually Yes (transient failures)
-
-> **Important:** `NETWORK_ERROR`, `TIMEOUT_ERROR`, and `RATE_LIMIT_ERROR` are error **codes** within `IngestionError`, not separate error classes. Check them using: `error instanceof IngestionError && error.code === IngestionErrorCode.NETWORK_ERROR`
-
-### State Management Errors (24xx)
-
-Errors related to state tracking and locking:
-
-```typescript
-export enum IngestionErrorCode {
-  LOCK_ACQUISITION_FAILED = 'LOCK_ACQUISITION_FAILED', // Failed to acquire lock
-  STATE_UPDATE_FAILED = 'STATE_UPDATE_FAILED',          // State update failed
-}
-```
-
-**When thrown:**
-- Distributed lock acquisition fails
-- KV store update fails
-- Concurrent processing conflict
-
-**Retryable:** Yes (transient issue)
-
-### Configuration Errors (25xx)
-
-Errors in SDK configuration:
-
-```typescript
-export enum IngestionErrorCode {
-  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',      // Generic config error
-  MISSING_REQUIRED_CONFIG = 'MISSING_REQUIRED_CONFIG', // Required config missing
-  INVALID_CONFIGURATION = 'INVALID_CONFIGURATION',  // Config value invalid
-}
-```
-
-**When thrown:**
-- Missing required environment variable
-- Invalid configuration value
-- Conflicting configuration options
-
-**Retryable:** No (configuration issue)
-
-### General Errors (26xx)
-
-General operational errors:
-
-```typescript
-export enum IngestionErrorCode {
-  UNKNOWN_ERROR = 'UNKNOWN_ERROR',                  // Unexpected error
-  TIMEOUT_ERROR = 'TIMEOUT_ERROR',                  // Operation timeout
-  RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',            // API rate limit hit
-}
-```
-
-**When thrown:**
-- Unexpected exception caught
-- Operation exceeds timeout
-- API rate limit reached
-
-**Retryable:** Depends (timeout/rate limit: yes, unknown: maybe)
-
-## Specific Error Classes
-
-### FileParsingError
-
-Thrown when file parsing fails:
-
-```typescript
-class FileParsingError extends IngestionError {
-  readonly fileName?: string;
-  readonly lineNumber?: number;
-}
-```
-
-**Example:**
-
-```typescript
-try {
-  const parsed = await parser.parse(xmlContent);
-} catch (error) {
-  if (error instanceof FileParsingError) {
-    console.error(`Parsing failed in ${error.fileName} at line ${error.lineNumber}`);
-    console.error(`Reason: ${error.message}`);
-    // Don't retry - fix source file
-  }
-}
-```
-
-**Common scenarios:**
-- Invalid XML: `<order><customer>Missing closing tag`
-- Invalid JSON: `{"key": value}` (unquoted value)
-- Malformed CSV: Inconsistent column count
-
-### PathResolutionError
-
-Thrown when source path doesn't exist in data:
-
-```typescript
-class PathResolutionError extends Error {
-  readonly path: string;
-  readonly cause?: Error;
-}
-```
-
-**Example:**
-
-```typescript
-// Mapping config
-{
-  "ref": {
-    "source": "order.WRONG_PATH.customer-email"
-  }
-}
-
-// Result
-try {
-  const payload = await mapper.map(parsed);
-} catch (error) {
-  if (error instanceof PathResolutionError) {
-    console.error(`Path not found: ${error.path}`);
-    // Don't retry - fix mapping configuration
-  }
-}
-```
-
-**Common scenarios:**
-- Typo in source path
-- Data structure changed
-- Optional field accessed without null check
-
-### MappingError
-
-Thrown when field mapping fails:
-
-```typescript
-class MappingError extends Error {
-  readonly field?: string;
-  readonly sourcePath?: string;
-}
-```
-
-**Example:**
-
-```typescript
-// Required field missing
-try {
-  const payload = await mapper.map(parsed);
-} catch (error) {
-  if (error instanceof MappingError) {
-    console.error(`Field: ${error.field}`);
-    console.error(`Source: ${error.sourcePath}`);
-    console.error(`Reason: ${error.message}`);
-    // Don't retry - fix data or mapping config
-  }
-}
-```
-
-**Common scenarios:**
-- Required field is missing or empty
-- Array validation failed (minItems, maxItems)
-- Type coercion failed
-
-### ValidationError
-
-Thrown when data validation rules fail:
-
-```typescript
-class ValidationError extends IngestionError {
-  readonly validationErrors: Array<{
-    field?: string;
-    value?: any;
-    rule?: string;
-    message: string;
-  }>;
-}
-```
-
-**Example:**
-
-```typescript
-try {
-  const result = await validator.validate(data);
-} catch (error) {
-  if (error instanceof ValidationError) {
-    error.validationErrors.forEach(err => {
-      console.error(`Field ${err.field} failed rule ${err.rule}: ${err.message}`);
-    });
-    // Don't retry - fix source data
-  }
-}
-```
-
-**Common scenarios:**
-- Email format invalid
-- Date in wrong format
-- Number out of range
-- Custom validation rule failed
-
-### ConfigurationError
-
-Thrown when SDK configuration is invalid:
-
-```typescript
-class ConfigurationError extends IngestionError {
-  readonly configKey?: string;
-}
-```
-
-**Example:**
-
-```typescript
-try {
-  const client = createClient({
-    baseUrl: undefined,  // ❌ Required
-  });
-} catch (error) {
-  if (error instanceof ConfigurationError) {
-    console.error(`Config error in ${error.configKey}: ${error.message}`);
-    // Don't retry - fix configuration
-  }
-}
-```
-
-**Common scenarios:**
-- Missing required environment variable
-- Invalid URL format
-- Conflicting configuration options
-
-### BatchSubmissionError
-
-Thrown when Batch API submission fails:
-
-```typescript
-class BatchSubmissionError extends IngestionError {
-  // Inherits all IngestionError properties
-}
-```
-
-**Example:**
-
-```typescript
-try {
-  await client.sendBatch(jobId, { entities: data });
-} catch (error) {
-  if (error instanceof BatchSubmissionError) {
-    console.error('Batch submission failed:', error.toJSON());
-
-    if (error.isRetryable()) {
-      // Retry with backoff
-      await retryWithBackoff(() => client.sendBatch(jobId, { entities: data }));
-    }
-  }
-}
-```
-
-**Common scenarios:**
-- Network timeout
-- API temporarily unavailable
-- Rate limit exceeded
-
-### AggregateIngestionError
-
-Thrown when multiple errors occur during batch processing:
-
-```typescript
-class AggregateIngestionError extends IngestionError {
-  readonly errors: IngestionError[];
-}
-```
-
-**Example:**
-
-```typescript
-try {
-  await processMultipleFiles(files);
-} catch (error) {
-  if (error instanceof AggregateIngestionError) {
-    console.error(`${error.errors.length} files failed:`);
-    error.errors.forEach(err => {
-      console.error(`- ${err.message} (${err.code})`);
-    });
-  }
-}
-```
-
-**Common scenarios:**
-- Batch file processing with some failures
-- Multiple validation errors in different fields
-- Parallel operations with multiple failures
-
-## Services for Error Recovery
-
-### PartialBatchRecovery
-
-`PartialBatchRecovery` handles partial batch failures gracefully, allowing you to retry only failed records instead of the entire batch.
-
-**Purpose:**
-- Track success/failure per record
-- Retry only failed records (not entire batch)
-- Reduce processing overhead on retries
-- Provide detailed error reporting per record
-
-**Example:**
-
-```typescript
-import { PartialBatchRecovery, createClient, createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-
-// Standalone
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'BatchRecovery' });
-
-// Versori Platform
-const { log: logger } = ctx;
-
-const recovery = new PartialBatchRecovery(logger);
-
-const result = await recovery.processBatchWithRecovery(
-  records,
-  async (batch) => {
-    // Your batch processing logic
-    const job = await client.createJob({ name: 'recovery', retailerId });
-    return await client.sendBatch(job.id, {
-      action: 'UPSERT',
-      entityType: 'INVENTORY',
-      entities: batch
-    });
-  },
-  {
-    maxRetries: 3,           // Maximum retry attempts per failed record
-    retryOnlyFailed: true,   // Only retry failed records (default: true)
-    batchSize: 100,          // Batch size for retries
-    retryDelay: 1000         // Delay between retries (ms)
-  }
-);
-
-console.log(`Success: ${result.successCount}, Failed: ${result.failedCount}`);
-console.log('Failed records:', result.failedRecords);
-```
-
-**Features:**
-- ✅ Track which specific records failed
-- ✅ Retry only failed records (not entire batch)
-- ✅ Configurable retry attempts
-- ✅ Detailed error reporting with record-level context
-- ✅ Exponential backoff between retries
-- ✅ Works with both Batch API and GraphQL mutations
-
-**Use Cases:**
-- Large batch imports where individual records may fail validation
-- Network-related partial failures
-- Rate limit handling with partial batch recovery
-- Data quality issues affecting subset of records
-
-**Return Value:**
-```typescript
-{
-  successCount: number;      // Total successful records
-  failedCount: number;       // Total failed records after all retries
-  failedRecords: Array<{     // Details of failed records
-    record: any;             // The record that failed
-    error: Error;            // The error that occurred
-    attemptCount: number;    // How many times it was retried
-  }>;
-}
-```
-
-### 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 });
-} catch (error) {
-  if (error instanceof GraphQLExecutionError) {
-    console.error('GraphQL errors:', error.getErrorMessages());
-
-    if (error.isAuthError()) {
-      logger.error('Authentication failed');
-    } else if (error.isValidationError()) {
-      logger.error('GraphQL validation failed');
-    }
-  }
-}
-```
-
-**Important:** Both `FluentClient` and `FluentVersoriClient` throw `GraphQLExecutionError` for GraphQL response errors. Previously, `FluentVersoriClient` returned errors in the response, but now it throws them for consistency and fail-fast behavior.
-
-**Common scenarios:**
-- GraphQL query/mutation validation errors
-- Field permission errors
-- Authentication/authorization failures
-- GraphQL 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 content = await s3DataSource.downloadFile(key);
-} catch (error) {
-  if (error instanceof DataSourceError) {
-    console.error('Data source operation failed:', {
-      source: error.source,      // 'S3_CSV' or 'SFTP_CSV'
-      operation: error.operation, // 'downloadFile'
-      details: error.details      // { bucket, key, statusCode }
-    });
-  }
-}
-```
-
-**Common scenarios:**
-- S3 download/upload failures
-- SFTP connection errors
-- File not found in bucket/server
-- Permission denied errors
-
-### ResolverError
-
-**Purpose:** Thrown when a custom resolver fails during field transformation
-
-**When it occurs:**
-- Custom resolver throws an exception
-- Resolver returns invalid type
-- Helper function fails in resolver
-
-**Example:**
-
-```typescript
-import { ResolverError, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-// Custom resolver that can throw ResolverError
-const customResolvers = {
-  'custom.validateEmail': (value: string) => {
-    if (!value.includes('@')) {
-      throw new Error('Invalid email format');
-    }
-    return value.toLowerCase();
-  },
-  '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: ${value}`);
-    }
-    return date.toISOString();
-  }
-};
-
-try {
-  const mapper = new UniversalMapper(config, { customResolvers });
-  const mapped = await mapper.map(data);
-} catch (error) {
-  if (error instanceof ResolverError) {
-    // Structured error with complete context
-    console.error('Resolver failed:', {
-      resolver: error.resolverName,          // 'custom.parseDate'
-      field: error.fieldName,                // 'orderDate'
-      path: error.fieldPath,                 // ['order', 'orderDate']
-      input: error.inputValueSnippet,        // 'invalid-date-string'
-      original: error.originalError.message, // Original error message
-      timestamp: error.timestamp
-    });
-
-    // Or use toJSON() for complete serialization
-    console.error('Complete error:', error.toJSON());
-  }
-}
-```
-
-**Error Properties:**
-- `resolverName`: Name of the resolver that failed (e.g., 'custom.parseDate')
-- `fieldName`: Target field name being transformed
-- `fieldPath`: Full path to the field in the data structure
-- `inputValue`: The value that caused the failure
-- `inputValueSnippet`: Truncated version of input for logging
-- `originalError`: The underlying error thrown by the resolver
-- `timestamp`: When the error occurred
-
-**Common scenarios:**
-- Custom date parsing failures
-- Email validation errors
-- Type conversion errors in resolvers
-- Custom validation logic failures
-- Transformation function exceptions
-
-**Note:** ResolverError does NOT extend `IngestionError` - always a permanent error indicating resolver implementation or data issues.
-
-## Using instanceof for Type Checking
-
-The SDK exports all error classes for type checking:
-
-```typescript
-import {
-  // Ingestion errors
-  IngestionError,
-  FileParsingError,
-  ValidationError,
-  ConfigurationError,
-  GraphQLExecutionError,
-
-  // Mapping errors
-  MappingError,
-  ResolverError,
-  PathResolutionError,
-
-  // Data source errors
-  DataSourceError,
-  
-  // Client errors (FluentClient and FluentVersoriClient)
-  FluentAPIError,
-  AuthenticationError
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function handleOperation() {
-  try {
-    await processData();
-  } catch (error) {
-    // Check most specific errors first
-    if (error instanceof FileParsingError) {
-      // Handle parsing errors
-      logError('Parsing failed', error);
-      throw error;  // Don't retry
-
-    } else if (error instanceof PathResolutionError) {
-      // Handle path errors
-      logError('Path resolution failed', error);
-      throw error;  // Don't retry
-
-    } else if (error instanceof MappingError) {
-      // Handle mapping errors
-      logError('Mapping failed', error);
-      throw error;  // Don't retry
-
-    } else if (error instanceof ValidationError) {
-      // Handle validation errors
-      logError('Validation failed', error);
-      throw error;  // Don't retry
-
-    } else if (error instanceof ConfigurationError) {
-      // Handle config errors
-      logError('Configuration invalid', error);
-      throw error;  // Don't retry
-
-    } else if (error instanceof FluentAPIError) {
-      // Handle API errors (400, 404, 500, etc.)
-      logError(`API Error: ${error.statusCode}`, error);
-      // Retry 5xx, fail 4xx
-      if (error.statusCode >= 500) {
-        return scheduleRetry();
-      }
-      throw error;
-
-    } else if (error instanceof AuthenticationError) {
-      // Handle Auth errors
-      logError('Authentication failed', error);
-      throw error; // Don't retry (already retried 3x)
-
-    } else if (error instanceof IngestionError) {
-      // Handle other ingestion errors
-      logError('Ingestion error', error);
-
-      // Check if retryable
-      if (error.isRetryable()) {
-        return scheduleRetry();
-      }
-      throw error;
-
-    } else {
-      // Unknown error
-      logError('Unknown error', error);
-      throw error;
-    }
-  }
-}
-```
-
-## Error Object Structure
-
-All SDK errors serialize to JSON with this structure:
-
-```typescript
-{
-  // Basic fields
-  name: "MappingError",
-  message: "Required field 'ref' is missing or empty",
-
-  // Error code (for programmatic handling)
-  code: "REQUIRED_FIELD_MISSING",
-
-  // Specific error details
-  field: "ref",
-  sourcePath: "order.ref",
-
-  // Additional context
-  context: {
-    recordIndex: 5,
-    fileName: "order-12345.xml",
-    mutation: "createOrder"
-  },
-
-  // Tracking
-  timestamp: "2025-01-10T12:34:56Z",
-  correlationId: "abc-123-def",
-
-  // Stack trace
-  stack: "Error: ...\n at ..."
-}
-```
-
-## Key Takeaways
-
-- 🎯 **Error hierarchy** - All ingestion errors extend `IngestionError`
-- 🎯 **Error codes** - Use `IngestionErrorCode` enum for programmatic handling
-- 🎯 **Specific classes** - Each error type has specific properties (fileName, field, etc.)
-- 🎯 **Type checking** - Use `instanceof` to handle different error types
-- 🎯 **JSON serialization** - All errors have `toJSON()` for logging
-- 🎯 **Retry detection** - Use `isRetryable()` to determine retry strategy
-
-## Practice Exercise
-
-Match the error class to the scenario:
-
-1. XML file has unclosed tag
-2. Mapping config references non-existent field path
-3. Required field is empty
-4. Network timeout during API call
-5. Missing environment variable
-
-<details>
-<summary>Click to see answers</summary>
-
-1. `FileParsingError` - Parsing failed
-2. `PathResolutionError` - Path doesn't exist
-3. `MappingError` - Field mapping failed
-4. `BatchSubmissionError` or `IngestionError` with `NETWORK_ERROR` - API error
-5. `ConfigurationError` - Config invalid
-
-</details>
-
-## Next Steps
-
-Continue to [Module 3: UTF-8 Handling →](./error-handling-03-utf8-handling.md) to learn about UTF-8 encoding and special character handling.
+# Module 2: Error Types & Codes
+
+**Level:** Beginner
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module provides a complete reference to all error types and error codes in the SDK, including the error class hierarchy and when each error is thrown.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand the error class hierarchy
+- ✅ Know all available error codes and their meanings
+- ✅ Recognize which error class is thrown for each scenario
+- ✅ Use `instanceof` checks to handle specific error types
+
+## Error Class Hierarchy
+
+```
+Error (JavaScript base class)
+  │
+  ├── IngestionError (Ingestion base class)
+  │     ├── FileDiscoveryError
+  │     ├── FileParsingError
+  │     ├── TransformationError
+  │     ├── BatchSubmissionError
+  │     ├── ConfigurationError
+  │     ├── ValidationError
+  │     ├── GraphQLExecutionError
+  │     └── AggregateIngestionError
+  │
+  ├── FluentError (Base SDK error class - used by services)
+  │     ├── FluentAPIError (HTTP errors from Fluent API)
+  │     ├── AuthenticationError (401 Unauthorized)
+  │     ├── FluentValidationError (Client-side validation)
+  │     ├── DataSourceError (S3/SFTP data source errors)
+  │     └── WebhookValidationError (Webhook signature validation errors)
+  │
+  ├── MappingError (Field mapping errors - standalone)
+  │
+  ├── ResolverError (Resolver transformation errors - standalone)
+  │
+  └── PathResolutionError (Path resolution errors - standalone)
+```
+
+**Key Points:**
+- `IngestionError` is the base class for all ingestion-related errors
+- `PathResolutionError`, `MappingError`, and `ResolverError` do NOT extend `IngestionError` - they are standalone error classes
+- `FluentError` is used by SDK services (S3, SFTP, webhooks) - separate from ingestion errors
+
+### Base Classes
+
+#### IngestionError (SDK Base)
+
+The base class for all ingestion-related errors:
+
+```typescript
+class IngestionError extends Error {
+  readonly code: IngestionErrorCode;
+  readonly context?: Record<string, any>;
+  readonly timestamp: Date;
+  readonly correlationId?: string;
+
+  toJSON(): Record<string, any>;
+  isRetryable(): boolean;
+}
+```
+
+**Key features:**
+- `code`: Machine-readable error code for programmatic handling
+- `context`: Additional error context (file name, record index, etc.)
+- `timestamp`: When the error occurred
+- `correlationId`: For tracking errors across distributed systems
+- `toJSON()`: Serialize error for logging/monitoring
+- `isRetryable()`: Check if error should be retried
+
+**Usage:**
+
+```typescript
+try {
+  await processFile(fileName);
+} catch (error) {
+  if (error instanceof IngestionError) {
+    console.log('Error code:', error.code);
+    console.log('Error JSON:', error.toJSON());
+    console.log('Can retry?', error.isRetryable());
+  }
+}
+```
+
+## Error Codes Reference
+
+### File Discovery Errors (20xx)
+
+Errors that occur when discovering or accessing files:
+
+```typescript
+export enum IngestionErrorCode {
+  FILE_DISCOVERY_FAILED = 'FILE_DISCOVERY_FAILED',  // Failed to discover files
+  FILE_ACCESS_DENIED = 'FILE_ACCESS_DENIED',        // Permission denied
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',                // File doesn't exist
+  INVALID_FILE_FORMAT = 'INVALID_FILE_FORMAT',      // Unsupported file type
+}
+```
+
+**When thrown:**
+- Listing S3 bucket fails
+- SFTP connection fails
+- File permissions insufficient
+- File path doesn't exist
+
+**Retryable:** Usually Yes (network issues)
+
+### Parsing Errors (21xx)
+
+Errors during file content parsing:
+
+```typescript
+export enum IngestionErrorCode {
+  PARSE_ERROR = 'PARSE_ERROR',                      // Generic parsing error
+  INVALID_CSV_FORMAT = 'INVALID_CSV_FORMAT',        // Malformed CSV
+  INVALID_PARQUET_FORMAT = 'INVALID_PARQUET_FORMAT', // Invalid Parquet file
+  ENCODING_ERROR = 'ENCODING_ERROR',                // Character encoding issue
+}
+```
+
+**When thrown:**
+- XML is malformed (missing closing tag)
+- JSON is invalid (syntax error)
+- CSV has inconsistent columns
+- Parquet file is corrupted
+- Character encoding is not UTF-8
+
+**Retryable:** No (source data issue)
+
+### Transformation Errors (22xx)
+
+Errors during field mapping and transformation:
+
+```typescript
+export enum IngestionErrorCode {
+  TRANSFORMATION_ERROR = 'TRANSFORMATION_ERROR',    // Generic transformation error
+  FIELD_MAPPING_ERROR = 'FIELD_MAPPING_ERROR',      // Field mapping failed
+  VALIDATION_ERROR = 'VALIDATION_ERROR',            // Data validation failed
+  REQUIRED_FIELD_MISSING = 'REQUIRED_FIELD_MISSING', // Required field empty
+}
+```
+
+**When thrown:**
+- Required field is missing or empty
+- Field type mismatch (expected number, got string)
+- Array validation failed (minItems, maxItems)
+- Custom resolver threw error
+- Source path doesn't exist in data
+
+**Retryable:** No (data or configuration issue)
+
+### Submission Errors (23xx)
+
+Errors when submitting to Fluent API:
+
+```typescript
+export enum IngestionErrorCode {
+  BATCH_SUBMISSION_ERROR = 'BATCH_SUBMISSION_ERROR', // Batch API error
+  JOB_CREATION_ERROR = 'JOB_CREATION_ERROR',        // Job creation failed
+  API_ERROR = 'API_ERROR',                          // Fluent API error
+  NETWORK_ERROR = 'NETWORK_ERROR',                  // Network connectivity
+}
+```
+
+**When thrown:**
+- Batch API returns error response
+- Job creation fails
+- Network timeout
+- API endpoint unreachable
+
+**Retryable:** Usually Yes (transient failures)
+
+> **Important:** `NETWORK_ERROR`, `TIMEOUT_ERROR`, and `RATE_LIMIT_ERROR` are error **codes** within `IngestionError`, not separate error classes. Check them using: `error instanceof IngestionError && error.code === IngestionErrorCode.NETWORK_ERROR`
+
+### State Management Errors (24xx)
+
+Errors related to state tracking and locking:
+
+```typescript
+export enum IngestionErrorCode {
+  LOCK_ACQUISITION_FAILED = 'LOCK_ACQUISITION_FAILED', // Failed to acquire lock
+  STATE_UPDATE_FAILED = 'STATE_UPDATE_FAILED',          // State update failed
+}
+```
+
+**When thrown:**
+- Distributed lock acquisition fails
+- KV store update fails
+- Concurrent processing conflict
+
+**Retryable:** Yes (transient issue)
+
+### Configuration Errors (25xx)
+
+Errors in SDK configuration:
+
+```typescript
+export enum IngestionErrorCode {
+  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',      // Generic config error
+  MISSING_REQUIRED_CONFIG = 'MISSING_REQUIRED_CONFIG', // Required config missing
+  INVALID_CONFIGURATION = 'INVALID_CONFIGURATION',  // Config value invalid
+}
+```
+
+**When thrown:**
+- Missing required environment variable
+- Invalid configuration value
+- Conflicting configuration options
+
+**Retryable:** No (configuration issue)
+
+### General Errors (26xx)
+
+General operational errors:
+
+```typescript
+export enum IngestionErrorCode {
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',                  // Unexpected error
+  TIMEOUT_ERROR = 'TIMEOUT_ERROR',                  // Operation timeout
+  RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',            // API rate limit hit
+}
+```
+
+**When thrown:**
+- Unexpected exception caught
+- Operation exceeds timeout
+- API rate limit reached
+
+**Retryable:** Depends (timeout/rate limit: yes, unknown: maybe)
+
+## Specific Error Classes
+
+### FileParsingError
+
+Thrown when file parsing fails:
+
+```typescript
+class FileParsingError extends IngestionError {
+  readonly fileName?: string;
+  readonly lineNumber?: number;
+}
+```
+
+**Example:**
+
+```typescript
+try {
+  const parsed = await parser.parse(xmlContent);
+} catch (error) {
+  if (error instanceof FileParsingError) {
+    console.error(`Parsing failed in ${error.fileName} at line ${error.lineNumber}`);
+    console.error(`Reason: ${error.message}`);
+    // Don't retry - fix source file
+  }
+}
+```
+
+**Common scenarios:**
+- Invalid XML: `<order><customer>Missing closing tag`
+- Invalid JSON: `{"key": value}` (unquoted value)
+- Malformed CSV: Inconsistent column count
+
+### PathResolutionError
+
+Thrown when source path doesn't exist in data:
+
+```typescript
+class PathResolutionError extends Error {
+  readonly path: string;
+  readonly cause?: Error;
+}
+```
+
+**Example:**
+
+```typescript
+// Mapping config
+{
+  "ref": {
+    "source": "order.WRONG_PATH.customer-email"
+  }
+}
+
+// Result
+try {
+  const payload = await mapper.map(parsed);
+} catch (error) {
+  if (error instanceof PathResolutionError) {
+    console.error(`Path not found: ${error.path}`);
+    // Don't retry - fix mapping configuration
+  }
+}
+```
+
+**Common scenarios:**
+- Typo in source path
+- Data structure changed
+- Optional field accessed without null check
+
+### MappingError
+
+Thrown when field mapping fails:
+
+```typescript
+class MappingError extends Error {
+  readonly field?: string;
+  readonly sourcePath?: string;
+}
+```
+
+**Example:**
+
+```typescript
+// Required field missing
+try {
+  const payload = await mapper.map(parsed);
+} catch (error) {
+  if (error instanceof MappingError) {
+    console.error(`Field: ${error.field}`);
+    console.error(`Source: ${error.sourcePath}`);
+    console.error(`Reason: ${error.message}`);
+    // Don't retry - fix data or mapping config
+  }
+}
+```
+
+**Common scenarios:**
+- Required field is missing or empty
+- Array validation failed (minItems, maxItems)
+- Type coercion failed
+
+### ValidationError
+
+Thrown when data validation rules fail:
+
+```typescript
+class ValidationError extends IngestionError {
+  readonly validationErrors: Array<{
+    field?: string;
+    value?: any;
+    rule?: string;
+    message: string;
+  }>;
+}
+```
+
+**Example:**
+
+```typescript
+try {
+  const result = await validator.validate(data);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    error.validationErrors.forEach(err => {
+      console.error(`Field ${err.field} failed rule ${err.rule}: ${err.message}`);
+    });
+    // Don't retry - fix source data
+  }
+}
+```
+
+**Common scenarios:**
+- Email format invalid
+- Date in wrong format
+- Number out of range
+- Custom validation rule failed
+
+### ConfigurationError
+
+Thrown when SDK configuration is invalid:
+
+```typescript
+class ConfigurationError extends IngestionError {
+  readonly configKey?: string;
+}
+```
+
+**Example:**
+
+```typescript
+try {
+  const client = createClient({
+    baseUrl: undefined,  // ❌ Required
+  });
+} catch (error) {
+  if (error instanceof ConfigurationError) {
+    console.error(`Config error in ${error.configKey}: ${error.message}`);
+    // Don't retry - fix configuration
+  }
+}
+```
+
+**Common scenarios:**
+- Missing required environment variable
+- Invalid URL format
+- Conflicting configuration options
+
+### BatchSubmissionError
+
+Thrown when Batch API submission fails:
+
+```typescript
+class BatchSubmissionError extends IngestionError {
+  // Inherits all IngestionError properties
+}
+```
+
+**Example:**
+
+```typescript
+try {
+  await client.sendBatch(jobId, { entities: data });
+} catch (error) {
+  if (error instanceof BatchSubmissionError) {
+    console.error('Batch submission failed:', error.toJSON());
+
+    if (error.isRetryable()) {
+      // Retry with backoff
+      await retryWithBackoff(() => client.sendBatch(jobId, { entities: data }));
+    }
+  }
+}
+```
+
+**Common scenarios:**
+- Network timeout
+- API temporarily unavailable
+- Rate limit exceeded
+
+### AggregateIngestionError
+
+Thrown when multiple errors occur during batch processing:
+
+```typescript
+class AggregateIngestionError extends IngestionError {
+  readonly errors: IngestionError[];
+}
+```
+
+**Example:**
+
+```typescript
+try {
+  await processMultipleFiles(files);
+} catch (error) {
+  if (error instanceof AggregateIngestionError) {
+    console.error(`${error.errors.length} files failed:`);
+    error.errors.forEach(err => {
+      console.error(`- ${err.message} (${err.code})`);
+    });
+  }
+}
+```
+
+**Common scenarios:**
+- Batch file processing with some failures
+- Multiple validation errors in different fields
+- Parallel operations with multiple failures
+
+## Services for Error Recovery
+
+### PartialBatchRecovery
+
+`PartialBatchRecovery` handles partial batch failures gracefully, allowing you to retry only failed records instead of the entire batch.
+
+**Purpose:**
+- Track success/failure per record
+- Retry only failed records (not entire batch)
+- Reduce processing overhead on retries
+- Provide detailed error reporting per record
+
+**Example:**
+
+```typescript
+import { PartialBatchRecovery, createClient, createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+
+// Standalone
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'BatchRecovery' });
+
+// Versori Platform
+const { log: logger } = ctx;
+
+const recovery = new PartialBatchRecovery(logger);
+
+const result = await recovery.processBatchWithRecovery(
+  records,
+  async (batch) => {
+    // Your batch processing logic
+    const job = await client.createJob({ name: 'recovery', retailerId });
+    return await client.sendBatch(job.id, {
+      action: 'UPSERT',
+      entityType: 'INVENTORY',
+      entities: batch
+    });
+  },
+  {
+    maxRetries: 3,           // Maximum retry attempts per failed record
+    retryOnlyFailed: true,   // Only retry failed records (default: true)
+    batchSize: 100,          // Batch size for retries
+    retryDelay: 1000         // Delay between retries (ms)
+  }
+);
+
+console.log(`Success: ${result.successCount}, Failed: ${result.failedCount}`);
+console.log('Failed records:', result.failedRecords);
+```
+
+**Features:**
+- ✅ Track which specific records failed
+- ✅ Retry only failed records (not entire batch)
+- ✅ Configurable retry attempts
+- ✅ Detailed error reporting with record-level context
+- ✅ Exponential backoff between retries
+- ✅ Works with both Batch API and GraphQL mutations
+
+**Use Cases:**
+- Large batch imports where individual records may fail validation
+- Network-related partial failures
+- Rate limit handling with partial batch recovery
+- Data quality issues affecting subset of records
+
+**Return Value:**
+```typescript
+{
+  successCount: number;      // Total successful records
+  failedCount: number;       // Total failed records after all retries
+  failedRecords: Array<{     // Details of failed records
+    record: any;             // The record that failed
+    error: Error;            // The error that occurred
+    attemptCount: number;    // How many times it was retried
+  }>;
+}
+```
+
+### 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 });
+} catch (error) {
+  if (error instanceof GraphQLExecutionError) {
+    console.error('GraphQL errors:', error.getErrorMessages());
+
+    if (error.isAuthError()) {
+      logger.error('Authentication failed');
+    } else if (error.isValidationError()) {
+      logger.error('GraphQL validation failed');
+    }
+  }
+}
+```
+
+**Important:** Both `FluentClient` and `FluentVersoriClient` throw `GraphQLExecutionError` for GraphQL response errors. Previously, `FluentVersoriClient` returned errors in the response, but now it throws them for consistency and fail-fast behavior.
+
+**Common scenarios:**
+- GraphQL query/mutation validation errors
+- Field permission errors
+- Authentication/authorization failures
+- GraphQL 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 content = await s3DataSource.downloadFile(key);
+} catch (error) {
+  if (error instanceof DataSourceError) {
+    console.error('Data source operation failed:', {
+      source: error.source,      // 'S3_CSV' or 'SFTP_CSV'
+      operation: error.operation, // 'downloadFile'
+      details: error.details      // { bucket, key, statusCode }
+    });
+  }
+}
+```
+
+**Common scenarios:**
+- S3 download/upload failures
+- SFTP connection errors
+- File not found in bucket/server
+- Permission denied errors
+
+### ResolverError
+
+**Purpose:** Thrown when a custom resolver fails during field transformation
+
+**When it occurs:**
+- Custom resolver throws an exception
+- Resolver returns invalid type
+- Helper function fails in resolver
+
+**Example:**
+
+```typescript
+import { ResolverError, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+// Custom resolver that can throw ResolverError
+const customResolvers = {
+  'custom.validateEmail': (value: string) => {
+    if (!value.includes('@')) {
+      throw new Error('Invalid email format');
+    }
+    return value.toLowerCase();
+  },
+  '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: ${value}`);
+    }
+    return date.toISOString();
+  }
+};
+
+try {
+  const mapper = new UniversalMapper(config, { customResolvers });
+  const mapped = await mapper.map(data);
+} catch (error) {
+  if (error instanceof ResolverError) {
+    // Structured error with complete context
+    console.error('Resolver failed:', {
+      resolver: error.resolverName,          // 'custom.parseDate'
+      field: error.fieldName,                // 'orderDate'
+      path: error.fieldPath,                 // ['order', 'orderDate']
+      input: error.inputValueSnippet,        // 'invalid-date-string'
+      original: error.originalError.message, // Original error message
+      timestamp: error.timestamp
+    });
+
+    // Or use toJSON() for complete serialization
+    console.error('Complete error:', error.toJSON());
+  }
+}
+```
+
+**Error Properties:**
+- `resolverName`: Name of the resolver that failed (e.g., 'custom.parseDate')
+- `fieldName`: Target field name being transformed
+- `fieldPath`: Full path to the field in the data structure
+- `inputValue`: The value that caused the failure
+- `inputValueSnippet`: Truncated version of input for logging
+- `originalError`: The underlying error thrown by the resolver
+- `timestamp`: When the error occurred
+
+**Common scenarios:**
+- Custom date parsing failures
+- Email validation errors
+- Type conversion errors in resolvers
+- Custom validation logic failures
+- Transformation function exceptions
+
+**Note:** ResolverError does NOT extend `IngestionError` - always a permanent error indicating resolver implementation or data issues.
+
+## Using instanceof for Type Checking
+
+The SDK exports all error classes for type checking:
+
+```typescript
+import {
+  // Ingestion errors
+  IngestionError,
+  FileParsingError,
+  ValidationError,
+  ConfigurationError,
+  GraphQLExecutionError,
+
+  // Mapping errors
+  MappingError,
+  ResolverError,
+  PathResolutionError,
+
+  // Data source errors
+  DataSourceError,
+  
+  // Client errors (FluentClient and FluentVersoriClient)
+  FluentAPIError,
+  AuthenticationError
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function handleOperation() {
+  try {
+    await processData();
+  } catch (error) {
+    // Check most specific errors first
+    if (error instanceof FileParsingError) {
+      // Handle parsing errors
+      logError('Parsing failed', error);
+      throw error;  // Don't retry
+
+    } else if (error instanceof PathResolutionError) {
+      // Handle path errors
+      logError('Path resolution failed', error);
+      throw error;  // Don't retry
+
+    } else if (error instanceof MappingError) {
+      // Handle mapping errors
+      logError('Mapping failed', error);
+      throw error;  // Don't retry
+
+    } else if (error instanceof ValidationError) {
+      // Handle validation errors
+      logError('Validation failed', error);
+      throw error;  // Don't retry
+
+    } else if (error instanceof ConfigurationError) {
+      // Handle config errors
+      logError('Configuration invalid', error);
+      throw error;  // Don't retry
+
+    } else if (error instanceof FluentAPIError) {
+      // Handle API errors (400, 404, 500, etc.)
+      logError(`API Error: ${error.statusCode}`, error);
+      // Retry 5xx, fail 4xx
+      if (error.statusCode >= 500) {
+        return scheduleRetry();
+      }
+      throw error;
+
+    } else if (error instanceof AuthenticationError) {
+      // Handle Auth errors
+      logError('Authentication failed', error);
+      throw error; // Don't retry (already retried 3x)
+
+    } else if (error instanceof IngestionError) {
+      // Handle other ingestion errors
+      logError('Ingestion error', error);
+
+      // Check if retryable
+      if (error.isRetryable()) {
+        return scheduleRetry();
+      }
+      throw error;
+
+    } else {
+      // Unknown error
+      logError('Unknown error', error);
+      throw error;
+    }
+  }
+}
+```
+
+## Error Object Structure
+
+All SDK errors serialize to JSON with this structure:
+
+```typescript
+{
+  // Basic fields
+  name: "MappingError",
+  message: "Required field 'ref' is missing or empty",
+
+  // Error code (for programmatic handling)
+  code: "REQUIRED_FIELD_MISSING",
+
+  // Specific error details
+  field: "ref",
+  sourcePath: "order.ref",
+
+  // Additional context
+  context: {
+    recordIndex: 5,
+    fileName: "order-12345.xml",
+    mutation: "createOrder"
+  },
+
+  // Tracking
+  timestamp: "2025-01-10T12:34:56Z",
+  correlationId: "abc-123-def",
+
+  // Stack trace
+  stack: "Error: ...\n at ..."
+}
+```
+
+## Key Takeaways
+
+- 🎯 **Error hierarchy** - All ingestion errors extend `IngestionError`
+- 🎯 **Error codes** - Use `IngestionErrorCode` enum for programmatic handling
+- 🎯 **Specific classes** - Each error type has specific properties (fileName, field, etc.)
+- 🎯 **Type checking** - Use `instanceof` to handle different error types
+- 🎯 **JSON serialization** - All errors have `toJSON()` for logging
+- 🎯 **Retry detection** - Use `isRetryable()` to determine retry strategy
+
+## Practice Exercise
+
+Match the error class to the scenario:
+
+1. XML file has unclosed tag
+2. Mapping config references non-existent field path
+3. Required field is empty
+4. Network timeout during API call
+5. Missing environment variable
+
+<details>
+<summary>Click to see answers</summary>
+
+1. `FileParsingError` - Parsing failed
+2. `PathResolutionError` - Path doesn't exist
+3. `MappingError` - Field mapping failed
+4. `BatchSubmissionError` or `IngestionError` with `NETWORK_ERROR` - API error
+5. `ConfigurationError` - Config invalid
+
+</details>
+
+## Next Steps
+
+Continue to [Module 3: UTF-8 Handling →](./error-handling-03-utf8-handling.md) to learn about UTF-8 encoding and special character handling.