@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-11-error-handling.md

@@ -1,716 +1,716 @@
-# Module 11: Error Handling
-
-**Level:** Intermediate to Advanced
-**Category:** Reliability & Resilience
-
-## Overview
-
-Robust error handling is critical for production integrations. The SDK provides comprehensive error types, retry strategies, partial batch recovery, and job tracking to handle failures gracefully and ensure data integrity.
-
-## Table of Contents
-
-- [Error Types](#error-types)
-- [Retry Strategies](#retry-strategies)
-- [PartialBatchRecovery Service](#partialbatchrecovery-service)
-- [JobTracker Service](#jobtracker-service)
-- [Error Recovery Patterns](#error-recovery-patterns)
-- [Logging and Monitoring](#logging-and-monitoring)
-- [Common Error Scenarios](#common-error-scenarios)
-- [Best Practices](#best-practices)
-- [Troubleshooting](#troubleshooting)
-- [See Also](#see-also)
-
----
-
-## Error Types
-
-The SDK defines custom error classes for different failure scenarios:
-
-### FluentAPIError
-
-API-level errors from Fluent Commerce:
-
-```typescript
-import { FluentAPIError } from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  await client.graphql({ query });
-} catch (error) {
-  if (error instanceof FluentAPIError) {
-    console.error('API Error:', {
-      statusCode: error.statusCode,     // HTTP status (400, 401, 500, etc.)
-      message: error.message,           // Error message
-      errors: error.errors,             // GraphQL errors array
-      requestId: error.requestId       // Request ID for support
-    });
-  }
-}
-```
-
-**Common Status Codes:**
-
-| Code | Meaning | Solution |
-|------|---------|----------|
-| 401 | Unauthorized | Check credentials, refresh token |
-| 403 | Forbidden | Verify permissions/scopes |
-| 429 | Rate Limited | Implement backoff, reduce request rate |
-| 500 | Server Error | Retry with exponential backoff |
-
-### AuthenticationError
-
-OAuth2 authentication failures (401 Unauthorized):
-
-```typescript
-import { AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  await client.sendEvent(event, 'sync');
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    console.error('Auth failed:', {
-      message: error.message,
-      statusCode: error.statusCode,  // Always 401
-      code: error.code,               // "AUTHENTICATION_ERROR"
-      details: error.details          // { response: "..." }
-    });
-    // Check credentials, refresh token
-  }
-}
-```
-
-**Note:** `FluentVersoriClient` throws `AuthenticationError` for 401 status codes (matching `FluentClient` behavior).
-
-### GraphQLExecutionError
-
-GraphQL query/mutation execution errors:
-
-```typescript
-import { GraphQLExecutionError } from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  await client.graphql({ query, variables });
-} catch (error) {
-  if (error instanceof GraphQLExecutionError) {
-    console.error('GraphQL Error:', {
-      message: error.message,
-      graphqlErrors: error.graphqlErrors,  // Array of GraphQL errors
-      query: error.query,                  // Original query
-      variables: error.variables          // Original variables
-    });
-    
-    // Check if validation error
-    if (error.isValidationError()) {
-      console.error('Validation failed');
-    }
-    
-    // Check if auth error
-    if (error.isAuthError()) {
-      console.error('Authentication failed');
-    }
-  }
-}
-```
-
-**Note:** Both `FluentClient` and `FluentVersoriClient` throw `GraphQLExecutionError` for GraphQL response errors (fail-fast behavior).
-
-### ValidationError
-
-Schema or data validation failures:
-
-```typescript
-import { ValidationError } from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  await mapper.map(sourceData, { validate: true });
-} catch (error) {
-  if (error instanceof ValidationError) {
-    console.error('Validation failed:', {
-      message: error.message,
-      field: error.field,          // Field that failed validation
-      value: error.value,          // Invalid value
-      constraint: error.constraint  // Validation rule violated
-    });
-  }
-}
-```
-
-### FluentVersoriClient Error Handling
-
-**Important:** `FluentVersoriClient` (used in Versori platform workflows) now throws structured errors matching `FluentClient` behavior:
-
-```typescript
-import { createClient, FluentAPIError, AuthenticationError, GraphQLExecutionError } from '@fluentcommerce/fc-connect-sdk';
-
-// In Versori workflow
-export const task = schedule('task', '0 2 * * *', async (ctx) => {
-  const client = await createClient(ctx); // Returns FluentVersoriClient
-  
-  try {
-    // Event API - throws FluentAPIError or AuthenticationError
-    await client.sendEvent(event, 'sync');
-  } catch (error) {
-    if (error instanceof AuthenticationError) {
-      // 401 Unauthorized
-      log.error('Auth failed', { statusCode: error.statusCode });
-    } else if (error instanceof FluentAPIError) {
-      // Other HTTP errors (400, 404, 422, 500, etc.)
-      log.error('API error', { 
-        statusCode: error.statusCode,
-        response: error.details?.response 
-      });
-    }
-  }
-  
-  try {
-    // GraphQL - throws GraphQLExecutionError or FluentAPIError
-    const result = await client.graphql({ query, variables });
-  } catch (error) {
-    if (error instanceof GraphQLExecutionError) {
-      // GraphQL response errors
-      log.error('GraphQL errors', { 
-        errors: error.graphqlErrors,
-        count: error.graphqlErrors.length 
-      });
-    } else if (error instanceof FluentAPIError) {
-      // HTTP errors (400, 401, 500, etc.)
-      log.error('HTTP error', { statusCode: error.statusCode });
-    }
-  }
-});
-```
-
-**Key Changes:**
-- ✅ GraphQL errors are **thrown** (not returned in response)
-- ✅ Event API errors throw `FluentAPIError` or `AuthenticationError`
-- ✅ All errors have structured properties (`statusCode`, `code`, `details`)
-- ✅ Backward compatible: generic `catch (error)` still works
-
-### NetworkError
-
-Connection and timeout errors:
-
-```typescript
-try {
-  await client.graphql({ query });
-} catch (error) {
-  if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT') {
-    console.error('Network error:', error.message);
-    // Retry with exponential backoff
-  }
-}
-```
-
----
-
-## Retry Strategies
-
-The SDK includes built-in retry logic for transient failures:
-
-### Automatic Retries
-
-FluentClient automatically retries failed requests:
-
-```typescript
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL,
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    retailerId: process.env.FLUENT_RETAILER_ID
-  },
-  retry: {
-    maxRetries: 3,              // Retry up to 3 times
-    initialDelayMs: 1000,       // Start with 1 second delay
-    maxDelayMs: 10000,          // Cap at 10 seconds
-    backoffMultiplier: 2,       // Double delay each retry
-    retryableStatusCodes: [408, 429, 500, 502, 503, 504]  // Retry these codes
-  }
-});
-```
-
-**Exponential Backoff:**
-- Retry 1: Wait 1 second
-- Retry 2: Wait 2 seconds
-- Retry 3: Wait 4 seconds
-- Retry 4: Wait 8 seconds (capped at maxDelayMs)
-
-### Manual Retry Logic
-
-For custom retry behavior:
-
-```typescript
-async function retryWithBackoff(fn, maxRetries = 3) {
-  let lastError;
-
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error;
-
-      // Don't retry on client errors (4xx except 429)
-      if (error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
-        throw error;
-      }
-
-      // Wait before retry (exponential backoff)
-      const delayMs = Math.min(1000 * Math.pow(2, i), 10000);
-      console.warn(`Retry ${i + 1}/${maxRetries} after ${delayMs}ms`);
-      await new Promise(resolve => setTimeout(resolve, delayMs));
-    }
-  }
-
-  throw lastError;
-}
-
-// Usage
-const result = await retryWithBackoff(() =>
-  client.graphql({ query })
-);
-```
-
----
-
-## PartialBatchRecovery Service
-
-Handles partial batch failures gracefully:
-
-```typescript
-import { createClient, PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config });
-const recovery = new PartialBatchRecovery(client, console);
-
-// Process batch with automatic retry of failed records
-const result = await recovery.processBatchWithRecovery({
-  records: inventoryUpdates,
-  batchSize: 500,
-  maxRetries: 3,
-  onPartialFailure: (failedRecords, successCount) => {
-    console.log(`${successCount} succeeded, ${failedRecords.length} failed`);
-  }
-});
-
-console.log('Final result:', {
-  totalProcessed: result.successCount,
-  failed: result.failedRecords.length,
-  errors: result.errors
-});
-```
-
-**Key Features:**
-- Identifies failed records from batch response
-- Retries only failed records (not entire batch)
-- Tracks failure counts per record
-- Provides detailed error reporting
-- Prevents infinite retry loops
-
-### Recovery Configuration
-
-```typescript
-await recovery.processBatchWithRecovery({
-  records: inventoryUpdates,
-  batchSize: 500,            // Initial batch size
-  maxRetries: 3,             // Per-record retry limit
-  retryDelayMs: 2000,        // Delay between retries
-  failFast: false,           // Continue on batch failure
-  onPartialFailure: (failedRecords, successCount) => {
-    // Log partial failures
-    console.log(`Partial failure: ${failedRecords.length} records failed`);
-  },
-  onRetry: (attempt, recordCount) => {
-    // Log retry attempts
-    console.log(`Retry ${attempt}: Processing ${recordCount} failed records`);
-  }
-});
-```
-
----
-
-## JobTracker Service
-
-Track job lifecycle and state:
-
-```typescript
-import { createClient, JobTracker } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config });
-const tracker = new JobTracker(client, console);
-
-// Create and track job
-const job = await tracker.createAndTrack({
-  type: 'INVENTORY_UPDATE',
-  retailerId: process.env.FLUENT_RETAILER_ID,
-  metadata: {
-    source: 'SFTP',
-    filename: 'inventory-2025-01-15.csv'
-  }
-});
-
-console.log('Job created:', job.id);
-
-// Send batches to job
-for (const batch of batches) {
-  await tracker.sendBatch(job.id, batch);
-}
-
-// Poll until complete
-const finalStatus = await tracker.pollUntilComplete(job.id, {
-  intervalMs: 5000,      // Check every 5 seconds
-  timeoutMs: 300000     // Timeout after 5 minutes
-});
-
-console.log('Job complete:', {
-  status: finalStatus.status,            // COMPLETED | FAILED | PARTIAL
-  recordsProcessed: finalStatus.recordsProcessed,
-  recordsFailed: finalStatus.recordsFailed,
-  errors: finalStatus.errors
-});
-```
-
-**Job States:**
-
-| State | Description | Next Actions |
-|-------|-------------|--------------|
-| CREATED | Job created, awaiting batches | Send batches |
-| PROCESSING | Batches being processed | Poll for completion |
-| COMPLETED | All records succeeded | Archive/cleanup |
-| PARTIAL | Some records failed | Review errors, retry |
-| FAILED | All records failed | Investigate root cause |
-
----
-
-## Error Recovery Patterns
-
-### Pattern 1: Checkpoint and Resume
-
-```typescript
-import { StateService } from '@fluentcommerce/fc-connect-sdk';
-
-const stateService = new StateService(kvAdapter);
-
-async function processFilesWithCheckpoints(files) {
-  for (const file of files) {
-    // Check if already processed
-    if (await stateService.isFileProcessed(file.name)) {
-      console.log(`Skipping ${file.name} (already processed)`);
-      continue;
-    }
-
-    try {
-      await processFile(file);
-
-      // Mark successful
-      await stateService.markFileProcessed(file.name, {
-        processedAt: new Date().toISOString(),
-        recordCount: file.recordCount
-      });
-    } catch (error) {
-      console.error(`Failed to process ${file.name}:`, error);
-
-      // Mark failed with retry count
-      await stateService.markFileFailed(file.name, {
-        error: error.message,
-        retryCount: (await stateService.getRetryCount(file.name)) + 1
-      });
-
-      // Skip if max retries exceeded
-      if (await stateService.getRetryCount(file.name) >= 3) {
-        console.error(`Max retries exceeded for ${file.name}`);
-        continue;
-      }
-
-      // Will retry on next run
-    }
-  }
-}
-```
-
-### Pattern 2: Dead Letter Queue
-
-```typescript
-const deadLetterQueue = [];
-
-async function processWithDLQ(records) {
-  for (const record of records) {
-    try {
-      await processRecord(record);
-    } catch (error) {
-      console.error(`Record failed:`, record.ref, error.message);
-
-      // Add to DLQ after max retries
-      if (record.retryCount >= 3) {
-        deadLetterQueue.push({
-          record,
-          error: error.message,
-          timestamp: new Date().toISOString()
-        });
-      } else {
-        // Retry later
-        record.retryCount = (record.retryCount || 0) + 1;
-        await queueForRetry(record);
-      }
-    }
-  }
-
-  // Export DLQ for manual review
-  if (deadLetterQueue.length > 0) {
-    await exportDLQ(deadLetterQueue);
-  }
-}
-```
-
-### Pattern 3: Circuit Breaker
-
-```typescript
-class CircuitBreaker {
-  constructor(threshold = 5, resetTimeMs = 60000) {
-    this.failureCount = 0;
-    this.threshold = threshold;
-    this.resetTimeMs = resetTimeMs;
-    this.state = 'CLOSED';  // CLOSED, OPEN, HALF_OPEN
-    this.lastFailureTime = null;
-  }
-
-  async execute(fn) {
-    if (this.state === 'OPEN') {
-      // Check if reset time has passed
-      if (Date.now() - this.lastFailureTime > this.resetTimeMs) {
-        this.state = 'HALF_OPEN';
-      } else {
-        throw new Error('Circuit breaker is OPEN');
-      }
-    }
-
-    try {
-      const result = await fn();
-
-      // Reset on success
-      if (this.state === 'HALF_OPEN') {
-        this.state = 'CLOSED';
-        this.failureCount = 0;
-      }
-
-      return result;
-    } catch (error) {
-      this.failureCount++;
-      this.lastFailureTime = Date.now();
-
-      if (this.failureCount >= this.threshold) {
-        this.state = 'OPEN';
-        console.warn('Circuit breaker opened');
-      }
-
-      throw error;
-    }
-  }
-}
-
-// Usage
-const breaker = new CircuitBreaker(5, 60000);
-
-await breaker.execute(() => client.graphql({ query }));
-```
-
----
-
-## Logging and Monitoring
-
-### Structured Logging
-
-```typescript
-import { LoggingService } from '@fluentcommerce/fc-connect-sdk';
-
-const log = new LoggingService('inventory-sync');
-
-try {
-  await processInventory();
-  log.info('Inventory sync complete', {
-    recordCount: 1000,
-    duration: 5000
-  });
-} catch (error) {
-  log.error('Inventory sync failed', {
-    error: error.message,
-    stack: error.stack,
-    context: {
-      filename: 'inventory.csv',
-      recordCount: 1000
-    }
-  });
-}
-```
-
-### Error Metrics
-
-```typescript
-const errorMetrics = {
-  totalErrors: 0,
-  errorsByType: {},
-  errorsByStatus: {}
-};
-
-try {
-  await client.graphql({ query });
-} catch (error) {
-  errorMetrics.totalErrors++;
-
-  if (error instanceof FluentAPIError) {
-    errorMetrics.errorsByStatus[error.statusCode] =
-      (errorMetrics.errorsByStatus[error.statusCode] || 0) + 1;
-  }
-
-  errorMetrics.errorsByType[error.constructor.name] =
-    (errorMetrics.errorsByType[error.constructor.name] || 0) + 1;
-
-  throw error;
-}
-
-// Report metrics
-console.log('Error metrics:', errorMetrics);
-```
-
----
-
-## Common Error Scenarios
-
-### Scenario 1: Transient Network Errors
-
-**Symptom:** Intermittent `ECONNRESET` or `ETIMEDOUT` errors
-
-**Solution:** Automatic retries with exponential backoff
-
-### Scenario 2: Rate Limiting (429)
-
-**Symptom:** "Too Many Requests" errors
-
-**Solution:** Implement delays between requests
-```typescript
-pagination: {
-  pageSize: 100,
-  delayMs: 1000  // 1 second delay
-}
-```
-
-### Scenario 3: Authentication Token Expiry
-
-**Symptom:** 401 errors mid-process
-
-**Solution:** FluentClient automatically refreshes tokens
-
-### Scenario 4: Partial Batch Failures
-
-**Symptom:** Some records succeed, others fail
-
-**Solution:** Use PartialBatchRecovery service
-
-### Scenario 5: Job Timeouts
-
-**Symptom:** Job stuck in PROCESSING state
-
-**Solution:** Implement timeout with JobTracker
-```typescript
-const status = await tracker.pollUntilComplete(jobId, {
-  timeoutMs: 300000  // 5-minute timeout
-});
-```
-
----
-
-## Best Practices
-
-1. **Always Handle Errors**
-   ```typescript
-   try {
-     await riskyOperation();
-   } catch (error) {
-     log.error('Operation failed', error);
-     // Handle gracefully
-   }
-   ```
-
-2. **Use Specific Error Types**
-   ```typescript
-   if (error instanceof AuthenticationError) {
-     // Re-authenticate
-   } else if (error instanceof ValidationError) {
-     // Fix data
-   }
-   ```
-
-3. **Implement Retries for Transient Errors**
-   ```typescript
-   retry: {
-     maxRetries: 3,
-     retryableStatusCodes: [408, 429, 500, 502, 503, 504]
-   }
-   ```
-
-4. **Track Failed Records**
-   ```typescript
-   const failed = [];
-   for (const record of records) {
-     try {
-       await process(record);
-     } catch (error) {
-       failed.push({ record, error });
-     }
-   }
-   // Export failed records for review
-   ```
-
-5. **Set Appropriate Timeouts**
-   ```typescript
-   const controller = new AbortController();
-   setTimeout(() => controller.abort(), 30000);
-   await client.graphql({ query, signal: controller.signal });
-   ```
-
----
-
-## Troubleshooting
-
-### Debug Mode
-
-Enable verbose logging:
-```typescript
-const log = new LoggingService('connector', { level: 'debug' });
-```
-
-### Error Stack Traces
-
-Preserve full stack traces:
-```typescript
-try {
-  await operation();
-} catch (error) {
-  console.error('Full error:', {
-    message: error.message,
-    stack: error.stack,
-    cause: error.cause
-  });
-  throw error;
-}
-```
-
----
-
-## See Also
-
-**Related Modules:**
-- [Module 05: Services](./api-reference-05-services.md) - PartialBatchRecovery, JobTracker
-- [Module 03: Authentication](./api-reference-03-authentication.md) - Token refresh handling
-
-**Complete Guides:**
-- [Error Handling Guide](../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - Comprehensive error patterns
-- [Batch Processing](../../ingestion/modules/02-core-guides-ingestion-06-batch-api.md) - Batch error recovery
-
-**Templates:**
-- [Error Handling Patterns](../../../01-TEMPLATES/patterns/error-handling-retry.md)
-
----
-
-**Navigation:**
-- [Back to Module List](./readme.md)
-- [Previous: Module 10 - Extraction](./api-reference-10-extraction.md)
-- [Next: Module 12 - Testing](./api-reference-12-testing.md)
+# Module 11: Error Handling
+
+**Level:** Intermediate to Advanced
+**Category:** Reliability & Resilience
+
+## Overview
+
+Robust error handling is critical for production integrations. The SDK provides comprehensive error types, retry strategies, partial batch recovery, and job tracking to handle failures gracefully and ensure data integrity.
+
+## Table of Contents
+
+- [Error Types](#error-types)
+- [Retry Strategies](#retry-strategies)
+- [PartialBatchRecovery Service](#partialbatchrecovery-service)
+- [JobTracker Service](#jobtracker-service)
+- [Error Recovery Patterns](#error-recovery-patterns)
+- [Logging and Monitoring](#logging-and-monitoring)
+- [Common Error Scenarios](#common-error-scenarios)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+- [See Also](#see-also)
+
+---
+
+## Error Types
+
+The SDK defines custom error classes for different failure scenarios:
+
+### FluentAPIError
+
+API-level errors from Fluent Commerce:
+
+```typescript
+import { FluentAPIError } from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  await client.graphql({ query });
+} catch (error) {
+  if (error instanceof FluentAPIError) {
+    console.error('API Error:', {
+      statusCode: error.statusCode,     // HTTP status (400, 401, 500, etc.)
+      message: error.message,           // Error message
+      errors: error.errors,             // GraphQL errors array
+      requestId: error.requestId       // Request ID for support
+    });
+  }
+}
+```
+
+**Common Status Codes:**
+
+| Code | Meaning | Solution |
+|------|---------|----------|
+| 401 | Unauthorized | Check credentials, refresh token |
+| 403 | Forbidden | Verify permissions/scopes |
+| 429 | Rate Limited | Implement backoff, reduce request rate |
+| 500 | Server Error | Retry with exponential backoff |
+
+### AuthenticationError
+
+OAuth2 authentication failures (401 Unauthorized):
+
+```typescript
+import { AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  await client.sendEvent(event, 'sync');
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Auth failed:', {
+      message: error.message,
+      statusCode: error.statusCode,  // Always 401
+      code: error.code,               // "AUTHENTICATION_ERROR"
+      details: error.details          // { response: "..." }
+    });
+    // Check credentials, refresh token
+  }
+}
+```
+
+**Note:** `FluentVersoriClient` throws `AuthenticationError` for 401 status codes (matching `FluentClient` behavior).
+
+### GraphQLExecutionError
+
+GraphQL query/mutation execution errors:
+
+```typescript
+import { GraphQLExecutionError } from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  await client.graphql({ query, variables });
+} catch (error) {
+  if (error instanceof GraphQLExecutionError) {
+    console.error('GraphQL Error:', {
+      message: error.message,
+      graphqlErrors: error.graphqlErrors,  // Array of GraphQL errors
+      query: error.query,                  // Original query
+      variables: error.variables          // Original variables
+    });
+    
+    // Check if validation error
+    if (error.isValidationError()) {
+      console.error('Validation failed');
+    }
+    
+    // Check if auth error
+    if (error.isAuthError()) {
+      console.error('Authentication failed');
+    }
+  }
+}
+```
+
+**Note:** Both `FluentClient` and `FluentVersoriClient` throw `GraphQLExecutionError` for GraphQL response errors (fail-fast behavior).
+
+### ValidationError
+
+Schema or data validation failures:
+
+```typescript
+import { ValidationError } from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  await mapper.map(sourceData, { validate: true });
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('Validation failed:', {
+      message: error.message,
+      field: error.field,          // Field that failed validation
+      value: error.value,          // Invalid value
+      constraint: error.constraint  // Validation rule violated
+    });
+  }
+}
+```
+
+### FluentVersoriClient Error Handling
+
+**Important:** `FluentVersoriClient` (used in Versori platform workflows) now throws structured errors matching `FluentClient` behavior:
+
+```typescript
+import { createClient, FluentAPIError, AuthenticationError, GraphQLExecutionError } from '@fluentcommerce/fc-connect-sdk';
+
+// In Versori workflow
+export const task = schedule('task', '0 2 * * *', async (ctx) => {
+  const client = await createClient(ctx); // Returns FluentVersoriClient
+  
+  try {
+    // Event API - throws FluentAPIError or AuthenticationError
+    await client.sendEvent(event, 'sync');
+  } catch (error) {
+    if (error instanceof AuthenticationError) {
+      // 401 Unauthorized
+      log.error('Auth failed', { statusCode: error.statusCode });
+    } else if (error instanceof FluentAPIError) {
+      // Other HTTP errors (400, 404, 422, 500, etc.)
+      log.error('API error', { 
+        statusCode: error.statusCode,
+        response: error.details?.response 
+      });
+    }
+  }
+  
+  try {
+    // GraphQL - throws GraphQLExecutionError or FluentAPIError
+    const result = await client.graphql({ query, variables });
+  } catch (error) {
+    if (error instanceof GraphQLExecutionError) {
+      // GraphQL response errors
+      log.error('GraphQL errors', { 
+        errors: error.graphqlErrors,
+        count: error.graphqlErrors.length 
+      });
+    } else if (error instanceof FluentAPIError) {
+      // HTTP errors (400, 401, 500, etc.)
+      log.error('HTTP error', { statusCode: error.statusCode });
+    }
+  }
+});
+```
+
+**Key Changes:**
+- ✅ GraphQL errors are **thrown** (not returned in response)
+- ✅ Event API errors throw `FluentAPIError` or `AuthenticationError`
+- ✅ All errors have structured properties (`statusCode`, `code`, `details`)
+- ✅ Backward compatible: generic `catch (error)` still works
+
+### NetworkError
+
+Connection and timeout errors:
+
+```typescript
+try {
+  await client.graphql({ query });
+} catch (error) {
+  if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT') {
+    console.error('Network error:', error.message);
+    // Retry with exponential backoff
+  }
+}
+```
+
+---
+
+## Retry Strategies
+
+The SDK includes built-in retry logic for transient failures:
+
+### Automatic Retries
+
+FluentClient automatically retries failed requests:
+
+```typescript
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL,
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    retailerId: process.env.FLUENT_RETAILER_ID
+  },
+  retry: {
+    maxRetries: 3,              // Retry up to 3 times
+    initialDelayMs: 1000,       // Start with 1 second delay
+    maxDelayMs: 10000,          // Cap at 10 seconds
+    backoffMultiplier: 2,       // Double delay each retry
+    retryableStatusCodes: [408, 429, 500, 502, 503, 504]  // Retry these codes
+  }
+});
+```
+
+**Exponential Backoff:**
+- Retry 1: Wait 1 second
+- Retry 2: Wait 2 seconds
+- Retry 3: Wait 4 seconds
+- Retry 4: Wait 8 seconds (capped at maxDelayMs)
+
+### Manual Retry Logic
+
+For custom retry behavior:
+
+```typescript
+async function retryWithBackoff(fn, maxRetries = 3) {
+  let lastError;
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      // Don't retry on client errors (4xx except 429)
+      if (error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
+        throw error;
+      }
+
+      // Wait before retry (exponential backoff)
+      const delayMs = Math.min(1000 * Math.pow(2, i), 10000);
+      console.warn(`Retry ${i + 1}/${maxRetries} after ${delayMs}ms`);
+      await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+  }
+
+  throw lastError;
+}
+
+// Usage
+const result = await retryWithBackoff(() =>
+  client.graphql({ query })
+);
+```
+
+---
+
+## PartialBatchRecovery Service
+
+Handles partial batch failures gracefully:
+
+```typescript
+import { createClient, PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config });
+const recovery = new PartialBatchRecovery(client, console);
+
+// Process batch with automatic retry of failed records
+const result = await recovery.processBatchWithRecovery({
+  records: inventoryUpdates,
+  batchSize: 500,
+  maxRetries: 3,
+  onPartialFailure: (failedRecords, successCount) => {
+    console.log(`${successCount} succeeded, ${failedRecords.length} failed`);
+  }
+});
+
+console.log('Final result:', {
+  totalProcessed: result.successCount,
+  failed: result.failedRecords.length,
+  errors: result.errors
+});
+```
+
+**Key Features:**
+- Identifies failed records from batch response
+- Retries only failed records (not entire batch)
+- Tracks failure counts per record
+- Provides detailed error reporting
+- Prevents infinite retry loops
+
+### Recovery Configuration
+
+```typescript
+await recovery.processBatchWithRecovery({
+  records: inventoryUpdates,
+  batchSize: 500,            // Initial batch size
+  maxRetries: 3,             // Per-record retry limit
+  retryDelayMs: 2000,        // Delay between retries
+  failFast: false,           // Continue on batch failure
+  onPartialFailure: (failedRecords, successCount) => {
+    // Log partial failures
+    console.log(`Partial failure: ${failedRecords.length} records failed`);
+  },
+  onRetry: (attempt, recordCount) => {
+    // Log retry attempts
+    console.log(`Retry ${attempt}: Processing ${recordCount} failed records`);
+  }
+});
+```
+
+---
+
+## JobTracker Service
+
+Track job lifecycle and state:
+
+```typescript
+import { createClient, JobTracker } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config });
+const tracker = new JobTracker(client, console);
+
+// Create and track job
+const job = await tracker.createAndTrack({
+  type: 'INVENTORY_UPDATE',
+  retailerId: process.env.FLUENT_RETAILER_ID,
+  metadata: {
+    source: 'SFTP',
+    filename: 'inventory-2025-01-15.csv'
+  }
+});
+
+console.log('Job created:', job.id);
+
+// Send batches to job
+for (const batch of batches) {
+  await tracker.sendBatch(job.id, batch);
+}
+
+// Poll until complete
+const finalStatus = await tracker.pollUntilComplete(job.id, {
+  intervalMs: 5000,      // Check every 5 seconds
+  timeoutMs: 300000     // Timeout after 5 minutes
+});
+
+console.log('Job complete:', {
+  status: finalStatus.status,            // COMPLETED | FAILED | PARTIAL
+  recordsProcessed: finalStatus.recordsProcessed,
+  recordsFailed: finalStatus.recordsFailed,
+  errors: finalStatus.errors
+});
+```
+
+**Job States:**
+
+| State | Description | Next Actions |
+|-------|-------------|--------------|
+| CREATED | Job created, awaiting batches | Send batches |
+| PROCESSING | Batches being processed | Poll for completion |
+| COMPLETED | All records succeeded | Archive/cleanup |
+| PARTIAL | Some records failed | Review errors, retry |
+| FAILED | All records failed | Investigate root cause |
+
+---
+
+## Error Recovery Patterns
+
+### Pattern 1: Checkpoint and Resume
+
+```typescript
+import { StateService } from '@fluentcommerce/fc-connect-sdk';
+
+const stateService = new StateService(kvAdapter);
+
+async function processFilesWithCheckpoints(files) {
+  for (const file of files) {
+    // Check if already processed
+    if (await stateService.isFileProcessed(file.name)) {
+      console.log(`Skipping ${file.name} (already processed)`);
+      continue;
+    }
+
+    try {
+      await processFile(file);
+
+      // Mark successful
+      await stateService.markFileProcessed(file.name, {
+        processedAt: new Date().toISOString(),
+        recordCount: file.recordCount
+      });
+    } catch (error) {
+      console.error(`Failed to process ${file.name}:`, error);
+
+      // Mark failed with retry count
+      await stateService.markFileFailed(file.name, {
+        error: error.message,
+        retryCount: (await stateService.getRetryCount(file.name)) + 1
+      });
+
+      // Skip if max retries exceeded
+      if (await stateService.getRetryCount(file.name) >= 3) {
+        console.error(`Max retries exceeded for ${file.name}`);
+        continue;
+      }
+
+      // Will retry on next run
+    }
+  }
+}
+```
+
+### Pattern 2: Dead Letter Queue
+
+```typescript
+const deadLetterQueue = [];
+
+async function processWithDLQ(records) {
+  for (const record of records) {
+    try {
+      await processRecord(record);
+    } catch (error) {
+      console.error(`Record failed:`, record.ref, error.message);
+
+      // Add to DLQ after max retries
+      if (record.retryCount >= 3) {
+        deadLetterQueue.push({
+          record,
+          error: error.message,
+          timestamp: new Date().toISOString()
+        });
+      } else {
+        // Retry later
+        record.retryCount = (record.retryCount || 0) + 1;
+        await queueForRetry(record);
+      }
+    }
+  }
+
+  // Export DLQ for manual review
+  if (deadLetterQueue.length > 0) {
+    await exportDLQ(deadLetterQueue);
+  }
+}
+```
+
+### Pattern 3: Circuit Breaker
+
+```typescript
+class CircuitBreaker {
+  constructor(threshold = 5, resetTimeMs = 60000) {
+    this.failureCount = 0;
+    this.threshold = threshold;
+    this.resetTimeMs = resetTimeMs;
+    this.state = 'CLOSED';  // CLOSED, OPEN, HALF_OPEN
+    this.lastFailureTime = null;
+  }
+
+  async execute(fn) {
+    if (this.state === 'OPEN') {
+      // Check if reset time has passed
+      if (Date.now() - this.lastFailureTime > this.resetTimeMs) {
+        this.state = 'HALF_OPEN';
+      } else {
+        throw new Error('Circuit breaker is OPEN');
+      }
+    }
+
+    try {
+      const result = await fn();
+
+      // Reset on success
+      if (this.state === 'HALF_OPEN') {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+      }
+
+      return result;
+    } catch (error) {
+      this.failureCount++;
+      this.lastFailureTime = Date.now();
+
+      if (this.failureCount >= this.threshold) {
+        this.state = 'OPEN';
+        console.warn('Circuit breaker opened');
+      }
+
+      throw error;
+    }
+  }
+}
+
+// Usage
+const breaker = new CircuitBreaker(5, 60000);
+
+await breaker.execute(() => client.graphql({ query }));
+```
+
+---
+
+## Logging and Monitoring
+
+### Structured Logging
+
+```typescript
+import { LoggingService } from '@fluentcommerce/fc-connect-sdk';
+
+const log = new LoggingService('inventory-sync');
+
+try {
+  await processInventory();
+  log.info('Inventory sync complete', {
+    recordCount: 1000,
+    duration: 5000
+  });
+} catch (error) {
+  log.error('Inventory sync failed', {
+    error: error.message,
+    stack: error.stack,
+    context: {
+      filename: 'inventory.csv',
+      recordCount: 1000
+    }
+  });
+}
+```
+
+### Error Metrics
+
+```typescript
+const errorMetrics = {
+  totalErrors: 0,
+  errorsByType: {},
+  errorsByStatus: {}
+};
+
+try {
+  await client.graphql({ query });
+} catch (error) {
+  errorMetrics.totalErrors++;
+
+  if (error instanceof FluentAPIError) {
+    errorMetrics.errorsByStatus[error.statusCode] =
+      (errorMetrics.errorsByStatus[error.statusCode] || 0) + 1;
+  }
+
+  errorMetrics.errorsByType[error.constructor.name] =
+    (errorMetrics.errorsByType[error.constructor.name] || 0) + 1;
+
+  throw error;
+}
+
+// Report metrics
+console.log('Error metrics:', errorMetrics);
+```
+
+---
+
+## Common Error Scenarios
+
+### Scenario 1: Transient Network Errors
+
+**Symptom:** Intermittent `ECONNRESET` or `ETIMEDOUT` errors
+
+**Solution:** Automatic retries with exponential backoff
+
+### Scenario 2: Rate Limiting (429)
+
+**Symptom:** "Too Many Requests" errors
+
+**Solution:** Implement delays between requests
+```typescript
+pagination: {
+  pageSize: 100,
+  delayMs: 1000  // 1 second delay
+}
+```
+
+### Scenario 3: Authentication Token Expiry
+
+**Symptom:** 401 errors mid-process
+
+**Solution:** FluentClient automatically refreshes tokens
+
+### Scenario 4: Partial Batch Failures
+
+**Symptom:** Some records succeed, others fail
+
+**Solution:** Use PartialBatchRecovery service
+
+### Scenario 5: Job Timeouts
+
+**Symptom:** Job stuck in PROCESSING state
+
+**Solution:** Implement timeout with JobTracker
+```typescript
+const status = await tracker.pollUntilComplete(jobId, {
+  timeoutMs: 300000  // 5-minute timeout
+});
+```
+
+---
+
+## Best Practices
+
+1. **Always Handle Errors**
+   ```typescript
+   try {
+     await riskyOperation();
+   } catch (error) {
+     log.error('Operation failed', error);
+     // Handle gracefully
+   }
+   ```
+
+2. **Use Specific Error Types**
+   ```typescript
+   if (error instanceof AuthenticationError) {
+     // Re-authenticate
+   } else if (error instanceof ValidationError) {
+     // Fix data
+   }
+   ```
+
+3. **Implement Retries for Transient Errors**
+   ```typescript
+   retry: {
+     maxRetries: 3,
+     retryableStatusCodes: [408, 429, 500, 502, 503, 504]
+   }
+   ```
+
+4. **Track Failed Records**
+   ```typescript
+   const failed = [];
+   for (const record of records) {
+     try {
+       await process(record);
+     } catch (error) {
+       failed.push({ record, error });
+     }
+   }
+   // Export failed records for review
+   ```
+
+5. **Set Appropriate Timeouts**
+   ```typescript
+   const controller = new AbortController();
+   setTimeout(() => controller.abort(), 30000);
+   await client.graphql({ query, signal: controller.signal });
+   ```
+
+---
+
+## Troubleshooting
+
+### Debug Mode
+
+Enable verbose logging:
+```typescript
+const log = new LoggingService('connector', { level: 'debug' });
+```
+
+### Error Stack Traces
+
+Preserve full stack traces:
+```typescript
+try {
+  await operation();
+} catch (error) {
+  console.error('Full error:', {
+    message: error.message,
+    stack: error.stack,
+    cause: error.cause
+  });
+  throw error;
+}
+```
+
+---
+
+## See Also
+
+**Related Modules:**
+- [Module 05: Services](./api-reference-05-services.md) - PartialBatchRecovery, JobTracker
+- [Module 03: Authentication](./api-reference-03-authentication.md) - Token refresh handling
+
+**Complete Guides:**
+- [Error Handling Guide](../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - Comprehensive error patterns
+- [Batch Processing](../../ingestion/modules/02-core-guides-ingestion-06-batch-api.md) - Batch error recovery
+
+**Templates:**
+- [Error Handling Patterns](../../../01-TEMPLATES/patterns/error-handling-retry.md)
+
+---
+
+**Navigation:**
+- [Back to Module List](./readme.md)
+- [Previous: Module 10 - Extraction](./api-reference-10-extraction.md)
+- [Next: Module 12 - Testing](./api-reference-12-testing.md)