@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

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

@@ -1,1061 +1,1061 @@
-# Module 5: Error Handling and Resilience
-
-> **Learning Objective:** Implement robust error handling, retry strategies, and resilience patterns for production-grade integrations.
->
-> **Level:** Intermediate
-
-## Table of Contents
-
-1. [Why Error Handling Matters](#why-error-handling-matters)
-2. [Error Categories](#error-categories)
-3. [SDK Error Handling](#sdk-error-handling)
-4. [Retry Strategies](#retry-strategies)
-5. [Circuit Breaker Pattern](#circuit-breaker-pattern)
-6. [Graceful Degradation](#graceful-degradation)
-7. [Logging and Monitoring](#logging-and-monitoring)
-8. [Error Recovery Patterns](#error-recovery-patterns)
-9. [Production Checklist](#production-checklist)
-10. [Complete Examples](#complete-examples)
-11. [Summary](#summary)
-
----
-
-## Why Error Handling Matters
-
-### Production Realities
-
-| Failure Type | Frequency | Impact | Recovery Time |
-|--------------|-----------|--------|---------------|
-| **Network Timeouts** | 1-5% of requests | Temporary | Seconds (retry) |
-| **API Rate Limits** | Variable | Temporary | Minutes (backoff) |
-| **Validation Errors** | 0.1-1% | Permanent | Manual fix |
-| **Service Outages** | Rare | Temporary | Minutes to hours |
-| **Bad Data** | 0.5-2% | Permanent | Manual fix |
-
-### Cost of Poor Error Handling
-
-```
-Scenario: 10,000 daily inventory updates, 1% error rate
-
-WITHOUT proper error handling:
-- 100 failed updates/day
-- No retry → permanent data loss
-- Manual investigation: 2 hours/day
-- Customer impact: Out-of-stock items shown available
-
-WITH proper error handling:
-- 100 initial failures
-- 95 recovered via retry (5 seconds)
-- 5 logged for manual review (15 minutes)
-- Customer impact: Minimal
-```
-
-### Error Handling Goals
-
-1. **Resilience**: Recover automatically from transient failures
-2. **Transparency**: Log errors with context for debugging
-3. **User Experience**: Provide meaningful error messages
-4. **Data Integrity**: Never lose data silently
-5. **Observability**: Monitor error rates and patterns
-
----
-
-## Error Categories
-
-### 1. Transient Errors (Retryable)
-
-**Cause**: Temporary conditions that may resolve
-
-| Error Type | HTTP Status | Retry? | Backoff | Example |
-|------------|-------------|--------|---------|---------|
-| **Network Timeout** | 504 | Yes | Exponential | Request timeout |
-| **Rate Limit** | 429 | Yes | Linear | Too many requests |
-| **Service Unavailable** | 503 | Yes | Exponential | API maintenance |
-| **Server Error** | 500 | Yes | Exponential | Internal error |
-
-### 2. Permanent Errors (Non-Retryable)
-
-**Cause**: Data or configuration issues requiring manual intervention
-
-| Error Type | HTTP Status | Retry? | Action | Example |
-|------------|-------------|--------|--------|---------|
-| **Validation Error** | 400 | No | Fix data | Missing required field |
-| **Authentication** | 401 | No | Fix credentials | Invalid token |
-| **Authorization** | 403 | No | Fix permissions | Insufficient access |
-| **Not Found** | 404 | No | Check config | Invalid endpoint |
-| **Unprocessable** | 422 | No | Fix data | Invalid field value |
-
-### 3. Partial Errors (Record-Level)
-
-**Cause**: Some records fail while others succeed
-
-| Scenario | Impact | Action | Example |
-|----------|--------|--------|---------|
-| **Batch API Errors** | Some records fail | Log failed records | 98/100 succeed |
-| **Mapping Errors** | Some records skip | Log validation errors | Missing SKU |
-| **GraphQL Errors** | Some mutations fail | Log errors, continue | Duplicate ref |
-
----
-
-## SDK Error Handling
-
-### FluentClient Error Handling
-
-The SDK automatically handles some errors:
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ /* config */ });
-
-try {
-  const result = await client.graphql({ query, variables });
-
-  // Check for GraphQL errors
-  if (result.errors && result.errors.length > 0) {
-    // Classify errors to determine retry strategy
-    const { classifyErrors } = await import('@fluentcommerce/fc-connect-sdk');
-    const classification = classifyErrors(result.errors);
-    
-    console.error('GraphQL errors:', {
-      errorCode: classification.errorCode,
-      retryable: classification.retryable,
-      action: classification.action,
-      message: classification.userMessage,
-      errors: result.errors,
-    });
-    
-    // Don't retry non-retryable errors
-    if (!classification.retryable) {
-      throw new Error(classification.userMessage);
-    }
-    
-    // result.data may still be partially populated for retryable errors
-  }
-
-} catch (error: any) {
-  // Network or authentication errors
-  console.error('Request failed:', error.message);
-
-  // Error types:
-  if (error.code === 'ECONNREFUSED') {
-    // Network error
-  } else if (error.statusCode === 401) {
-    // Authentication error
-  } else if (error.statusCode === 429) {
-    // Rate limit
-  }
-}
-```
-
-### Batch API Error Handling
-
-```typescript
-// Create job
-const job = await client.createJob({ name: 'Inventory Sync', retailerId: '2' });
-
-// Send batches
-for (const batch of batches) {
-  try {
-    await client.sendBatch(job.id, { entities: batch });
-  } catch (error: any) {
-    console.error('Batch send failed:', error.message);
-    // Log failed batch for retry
-  }
-}
-
-// Check job status
-const status = await client.getJobStatus(job.id);
-
-if (status.errorSummary && status.errorSummary.totalErrors > 0) {
-  console.warn(`Job completed with ${status.errorSummary.totalErrors} errors`);
-
-  // Get error details
-  const errors = await client.graphql({
-    query: `
-      query GetJobErrors($jobId: ID!) {
-        job(id: $jobId) {
-          batches(first: 100) {
-            edges {
-              node {
-                errors {
-                  recordRef
-                  errorType
-                  errorMessage
-                }
-              }
-            }
-          }
-        }
-      }
-    `,
-    variables: { jobId: job.id }
-  });
-
-  // Log errors for manual review
-  console.error('Batch errors:', JSON.stringify(errors, null, 2));
-}
-```
-
-### UniversalMapper Error Handling
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper(mappingConfig);
-
-const successfulRecords = [];
-const failedRecords = [];
-
-for (const record of records) {
-  const result = await mapper.map(record);
-
-  if (result.success) {
-    successfulRecords.push(result.data);
-  } else {
-    failedRecords.push({
-      record,
-      errors: result.errors
-    });
-  }
-}
-
-console.log(`Mapped ${successfulRecords.length} records, ${failedRecords.length} failures`);
-
-// Write failed records to error file
-if (failedRecords.length > 0) {
-  await fs.writeFile(
-    'mapping-errors.json',
-    JSON.stringify(failedRecords, null, 2)
-  );
-}
-```
-
----
-
-## Retry Strategies
-
-### Pattern 1: Exponential Backoff
-
-**Best for**: Network errors, rate limits, server errors
-
-```typescript
-/**
- * Exponential Backoff Retry
- *
- * Delay = initialDelay * (2 ^ attempt)
- * Example: 1s, 2s, 4s, 8s, 16s
- */
-
-async function exponentialBackoff<T>(
-  fn: () => Promise<T>,
-  options = {
-    maxRetries: 5,
-    initialDelay: 1000,
-    maxDelay: 30000
-  }
-): Promise<T> {
-  let lastError: Error;
-
-  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
-    try {
-      return await fn();
-
-    } catch (error: any) {
-      lastError = error;
-
-      // Don't retry permanent errors
-      if (error.statusCode && error.statusCode < 500) {
-        throw error;
-      }
-
-      if (attempt < options.maxRetries) {
-        // Calculate delay
-        const delay = Math.min(
-          options.initialDelay * Math.pow(2, attempt),
-          options.maxDelay
-        );
-
-        console.log(`Retry ${attempt + 1}/${options.maxRetries} after ${delay}ms`);
-
-        await sleep(delay);
-      }
-    }
-  }
-
-  throw lastError!;
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-// Usage
-const result = await exponentialBackoff(() =>
-    client.graphql({ query, variables })
-);
-```
-
-### Pattern 2: Linear Backoff (Rate Limits)
-
-**Best for**: Rate limit errors (429)
-
-```typescript
-/**
- * Linear Backoff for Rate Limits
- *
- * Delay = retryAfter (from response header)
- */
-
-async function linearBackoff<T>(
-  fn: () => Promise<T>,
-  maxRetries = 3
-): Promise<T> {
-  let lastError: Error;
-
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await fn();
-
-    } catch (error: any) {
-      lastError = error;
-
-      if (error.statusCode === 429) {
-        // Check for Retry-After header
-        const retryAfter = error.headers?.['retry-after'];
-        const delay = retryAfter ? parseInt(retryAfter) * 1000 : 60000;
-
-        console.log(`Rate limited - retry after ${delay}ms`);
-
-        await sleep(delay);
-      } else {
-        throw error; // Not a rate limit error
-      }
-    }
-  }
-
-  throw lastError!;
-}
-
-// Usage
-const result = await linearBackoff(() =>
-    client.graphql({ query, variables })
-);
-```
-
-### Pattern 3: Jittered Backoff
-
-**Best for**: High concurrency to avoid thundering herd
-
-```typescript
-/**
- * Jittered Exponential Backoff
- *
- * Adds randomness to avoid synchronized retries
- */
-
-function jitteredBackoff(attempt: number, baseDelay = 1000, maxDelay = 30000): number {
-  const exponentialDelay = baseDelay * Math.pow(2, attempt);
-  const jitter = Math.random() * exponentialDelay * 0.3; // ±30% jitter
-  return Math.min(exponentialDelay + jitter, maxDelay);
-}
-
-async function retryWithJitter<T>(
-  fn: () => Promise<T>,
-  maxRetries = 5
-): Promise<T> {
-  let lastError: Error;
-
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await fn();
-
-    } catch (error: any) {
-      lastError = error;
-
-      if (error.statusCode && error.statusCode < 500) {
-        throw error; // Don't retry permanent errors
-      }
-
-      if (attempt < maxRetries) {
-        const delay = jitteredBackoff(attempt);
-        console.log(`Retry ${attempt + 1} after ${delay.toFixed(0)}ms`);
-        await sleep(delay);
-      }
-    }
-  }
-
-  throw lastError!;
-}
-```
-
----
-
-## Circuit Breaker Pattern
-
-### Concept
-
-**Prevent cascading failures** by stopping requests to failing services.
-
-```
-States:
-┌─────────┐
-│ CLOSED  │  Normal operation, allow all requests
-└────┬────┘
-     │ Failure threshold reached (e.g., 5 failures)
-     ▼
-┌─────────┐
-│  OPEN   │  Block all requests, return error immediately
-└────┬────┘
-     │ Timeout elapsed (e.g., 60 seconds)
-     ▼
-┌─────────┐
-│HALF-OPEN│  Allow limited requests to test recovery
-└────┬────┘
-     │ Success → CLOSED
-     │ Failure → OPEN
-```
-
-### Implementation
-
-```typescript
-/**
- * Circuit Breaker
- *
- * Prevents cascading failures by stopping requests to failing services
- */
-
-class CircuitBreaker {
-  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
-  private failures = 0;
-  private lastFailureTime = 0;
-
-  constructor(
-    private options = {
-      failureThreshold: 5,
-      resetTimeout: 60000,
-      halfOpenRequests: 3
-    }
-  ) {}
-
-  async execute<T>(fn: () => Promise<T>): Promise<T> {
-    // Check state
-    if (this.state === 'OPEN') {
-      // Check if timeout elapsed
-      if (Date.now() - this.lastFailureTime > this.options.resetTimeout) {
-        console.log('Circuit HALF-OPEN');
-        this.state = 'HALF_OPEN';
-      } else {
-        throw new Error('Circuit breaker is OPEN - blocking requests');
-      }
-    }
-
-    try {
-      const result = await fn();
-
-      // Success - reset failures
-      if (this.state === 'HALF_OPEN') {
-        console.log('Circuit CLOSED');
-        this.state = 'CLOSED';
-      }
-      this.failures = 0;
-
-      return result;
-
-    } catch (error) {
-      this.failures++;
-      this.lastFailureTime = Date.now();
-
-      if (this.failures >= this.options.failureThreshold) {
-        console.log('Circuit OPEN - failure threshold reached');
-        this.state = 'OPEN';
-      }
-
-      throw error;
-    }
-  }
-}
-
-// Usage
-const breaker = new CircuitBreaker({
-  failureThreshold: 5,
-  resetTimeout: 60000
-});
-
-try {
-  const result = await breaker.execute(() =>
-    client.graphql({ query, variables })
-  );
-} catch (error: any) {
-  if (error.message.includes('Circuit breaker is OPEN')) {
-    console.error('Service is down - circuit breaker active');
-    // Use fallback or queue for later
-  } else {
-    throw error;
-  }
-}
-```
-
----
-
-## Graceful Degradation
-
-### Pattern 1: Fallback Values
-
-**Provide defaults** when non-critical data is unavailable.
-
-```typescript
-async function getProductDetails(sku: string): Promise<any> {
-  try {
-    const product = await client.graphql({
-      query: `query GetProduct($sku: String!) {
-        products(ref: $sku, first: 1) {
-          edges {
-            node {
-              id
-              ref
-              name
-              price
-            }
-          }
-        }
-      }`,
-      variables: { sku }
-    });
-
-    return product?.products?.edges?.[0]?.node;
-
-  } catch (error: any) {
-    console.warn(`Failed to fetch product ${sku}, using defaults`, error);
-
-    // Return fallback
-    return {
-      id: null,
-      ref: sku,
-      name: 'Product details unavailable',
-      price: 0
-    };
-  }
-}
-```
-
-### Pattern 2: Partial Failure Handling
-
-**Process successful records** even if some fail.
-
-```typescript
-async function processOrders(orders: any[]): Promise<{
-  successful: any[];
-  failed: any[];
-}> {
-  const successful = [];
-  const failed = [];
-
-  for (const order of orders) {
-    try {
-      const result = await client.graphql({
-        query: CREATE_ORDER_MUTATION,
-        variables: { input: order }
-      });
-
-      successful.push({ order, result });
-
-    } catch (error: any) {
-      console.error(`Failed to process order ${order.ref}`, error);
-
-      failed.push({ order, error: error.message });
-
-      // Continue with next order (don't throw)
-    }
-  }
-
-  console.log(`Processed ${successful.length} orders, ${failed.length} failures`);
-
-  // Write failed orders for retry
-  if (failed.length > 0) {
-    await fs.writeFile('failed-orders.json', JSON.stringify(failed, null, 2));
-  }
-
-  return { successful, failed };
-}
-```
-
-### Pattern 3: Queue for Retry
-
-**Queue failed operations** for later retry.
-
-```typescript
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-async function processWithQueue(records: any[]) {
-  const kvAdapter = new VersoriKVAdapter(openKv());
-  const stateService = new StateService(logger);
-
-  for (const record of records) {
-    try {
-      await processRecord(record);
-
-    } catch (error: any) {
-      console.error(`Failed to process record ${record.id}`, error);
-
-      // Add to retry queue
-      const queue = await stateService.getState('retry-queue') || [];
-      queue.push({
-        record,
-        error: error.message,
-        timestamp: Date.now(),
-        retryCount: 0
-      });
-      await stateService.setState('retry-queue', queue);
-    }
-  }
-}
-
-// Separate process to retry queued items
-async function retryQueue() {
-  const kvAdapter = new VersoriKVAdapter(openKv());
-  const stateService = new StateService(logger);
-
-  const queue = await stateService.getState('retry-queue') || [];
-  const remainingQueue = [];
-
-  for (const item of queue) {
-    try {
-      await processRecord(item.record);
-      console.log(`✓ Retry succeeded for ${item.record.id}`);
-
-    } catch (error: any) {
-      item.retryCount++;
-
-      if (item.retryCount < 3) {
-        // Re-queue
-        remainingQueue.push(item);
-      } else {
-        // Max retries reached - log as permanent failure
-        console.error(`✗ Max retries reached for ${item.record.id}`);
-      }
-    }
-  }
-
-  await stateService.setState('retry-queue', remainingQueue);
-}
-```
-
----
-
-## Logging and Monitoring
-
-### Structured Logging
-
-**Use SDK logging utilities** for consistent format and easy parsing.
-
-```typescript
-import {
-  createConsoleLogger,
-  toStructuredLogger,
-  generateCorrelationId
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Basic console logger
-const logger = createConsoleLogger();
-
-// Or with structured context
-const contextLogger = toStructuredLogger(logger, {
-  service: 'InventorySync',
-  correlationId: generateCorrelationId(),
-  environment: 'production'
-});
-
-// Usage
-contextLogger.info('Processing inventory file', {
-  fileName: 'inventory.csv',
-  recordCount: 5000
-});
-// Output: [INFO] Processing inventory file
-//         {"service":"InventorySync","correlationId":"...","fileName":"inventory.csv","recordCount":5000}
-
-contextLogger.error('Batch API error', error, {
-  jobId: job.id,
-  batchId: batch.id
-});
-// Output: [ERROR] Batch API error
-//         {"service":"InventorySync","error":"...","stack":"...","jobId":"...","batchId":"..."}
-```
-
-**For Versori Platform:**
-
-```typescript
-// ✅ CORRECT - Use native log from context
-import { schedule } from '@versori/run';
-
-export const myWorkflow = schedule('workflow', '0 * * * *')
-  .execute(async ({ log }) => {
-    // Use native log directly - don't wrap it!
-    log.info('Processing started');
-    log.error('Processing failed', error);
-  });
-```
-
-### Error Metrics
-
-**Track error rates** for monitoring.
-
-```typescript
-class ErrorMetrics {
-  private errors: Map<string, number> = new Map();
-  private total = 0;
-
-  recordError(type: string) {
-    this.errors.set(type, (this.errors.get(type) || 0) + 1);
-    this.total++;
-  }
-
-  getMetrics() {
-    const metrics: any = {
-      totalErrors: this.total,
-      errorsByType: {}
-    };
-
-    for (const [type, count] of this.errors.entries()) {
-      metrics.errorsByType[type] = {
-        count,
-        percentage: ((count / this.total) * 100).toFixed(2) + '%'
-      };
-    }
-
-    return metrics;
-  }
-
-  reset() {
-    this.errors.clear();
-    this.total = 0;
-  }
-}
-
-// Usage
-const metrics = new ErrorMetrics();
-
-try {
-  await processRecord(record);
-} catch (error: any) {
-  if (error.statusCode === 429) {
-    metrics.recordError('RATE_LIMIT');
-  } else if (error.statusCode >= 500) {
-    metrics.recordError('SERVER_ERROR');
-  } else {
-    metrics.recordError('VALIDATION_ERROR');
-  }
-}
-
-// Log metrics periodically
-console.log('Error metrics:', metrics.getMetrics());
-```
-
----
-
-## Error Recovery Patterns
-
-### Pattern 1: Dead Letter Queue
-
-**Store failed records** for manual review.
-
-```typescript
-async function processWithDLQ(records: any[]) {
-  const successCount = 0;
-  const dlq: any[] = [];
-
-  for (const record of records) {
-    try {
-      await processRecord(record);
-      successCount++;
-
-    } catch (error: any) {
-      // Add to dead letter queue
-      dlq.push({
-        record,
-        error: error.message,
-        stack: error.stack,
-        timestamp: new Date().toISOString(),
-        context: {
-          fileName: 'inventory.csv',
-          lineNumber: record._lineNumber
-        }
-      });
-    }
-  }
-
-  // Write DLQ to file
-  if (dlq.length > 0) {
-    await fs.writeFile(
-      `dlq-${Date.now()}.json`,
-      JSON.stringify(dlq, null, 2)
-    );
-
-    console.log(`Processed ${successCount} records, ${dlq.length} in DLQ`);
-  }
-}
-```
-
-### Pattern 2: Compensating Transaction
-
-**Undo partial changes** on failure.
-
-```typescript
-async function createOrderWithRollback(orderData: any) {
-  let customerId: string | null = null;
-
-  try {
-    // Step 1: Create customer
-    const customer = await client.graphql({
-      query: CREATE_CUSTOMER_MUTATION,
-      variables: { input: orderData.customer }
-    });
-    customerId = customer.id;
-
-    // Step 2: Create order
-    const order = await client.graphql({
-      query: CREATE_ORDER_MUTATION,
-      variables: {
-        input: {
-          ...orderData,
-          customer: { id: customerId }
-        }
-      }
-    });
-
-    return order;
-
-  } catch (error: any) {
-    console.error('Order creation failed', error);
-
-    // Rollback: Delete customer if created
-    if (customerId) {
-      try {
-        await client.graphql({
-          query: DELETE_CUSTOMER_MUTATION,
-          variables: { id: customerId }
-        });
-        console.log(`Rolled back customer ${customerId}`);
-      } catch (rollbackError) {
-        console.error('Rollback failed', rollbackError);
-      }
-    }
-
-    throw error;
-  }
-}
-```
-
----
-
-## Production Checklist
-
-### Before Deployment
-
-- [ ] **Error handling** for all API calls
-- [ ] **Retry logic** for transient errors
-- [ ] **Validation** for all input data
-- [ ] **Logging** with structured format
-- [ ] **Error metrics** and monitoring
-- [ ] **Circuit breaker** for external dependencies
-- [ ] **Graceful degradation** for non-critical failures
-- [ ] **Dead letter queue** for failed records
-- [ ] **Idempotency** for duplicate prevention
-- [ ] **Timeout configuration** for all operations
-- [ ] **Rate limit handling** with backoff
-- [ ] **Security** (signature verification, IP allowlist)
-- [ ] **Health check** endpoint
-- [ ] **Error documentation** for ops team
-
-### Monitoring
-
-- [ ] **Error rate** (< 1% target)
-- [ ] **Retry rate** (< 5% target)
-- [ ] **Response time** (p50, p95, p99)
-- [ ] **Success rate** (> 99% target)
-- [ ] **DLQ size** (alert if > 100)
-- [ ] **Circuit breaker** state changes
-- [ ] **Queue depth** (for async processing)
-
----
-
-## Complete Examples
-
-### Production-Ready Webhook with Full Error Handling
-
-```typescript
-/**
- * Production-ready webhook with comprehensive error handling
- */
-
-import { createClient, GraphQLMutationMapper, StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export default async function productionWebhook(activation: any, log: any, connections: any) {
-  const startTime = Date.now();
-  const webhookId = activation.headers['x-webhook-id'] || crypto.randomUUID();
-
-  try {
-    log.info('Webhook received', {
-      webhookId,
-      source: activation.headers['user-agent']
-    });
-
-    // Idempotency check
-    const kvAdapter = new VersoriKVAdapter(openKv());
-    const stateService = new StateService(logger);
-
-    const processed = await stateService.getState(`webhook:${webhookId}`);
-    if (processed) {
-      log.info('Webhook already processed', { webhookId });
-      return {
-        status: 200,
-        body: {
-          success: true,
-          message: 'Already processed',
-          orderId: processed.orderId
-        }
-      };
-    }
-
-    // Validate payload
-    if (!activation.body || !activation.body.orderRef) {
-      throw new Error('Missing required field: orderRef');
-    }
-
-    // Create client with retry
-    const client = await retryWithJitter(() =>
-      createClient({
-        connection: connections.fluent_commerce,
-        logger: log
-      })
-    );
-
-    // Process order
-    const result = await retryWithJitter(() =>
-      client.graphql({
-        query: CREATE_ORDER_MUTATION,
-        variables: { input: mapOrderData(activation.body) }
-      })
-    );
-
-    // Mark as processed
-    await stateService.setState(`webhook:${webhookId}`, {
-      orderId: result.id,
-      processedAt: new Date().toISOString()
-    });
-
-    const duration = Date.now() - startTime;
-
-    log.info('Webhook processed successfully', {
-      webhookId,
-      orderId: result.id,
-      duration
-    });
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        orderId: result.id,
-        duration
-      }
-    };
-
-  } catch (error: any) {
-    const duration = Date.now() - startTime;
-
-    log.error('Webhook processing failed', error, {
-      webhookId,
-      duration
-    });
-
-    // Categorize error
-    if (error.message.includes('required field')) {
-      return {
-        status: 400,
-        body: {
-          success: false,
-          error: 'Validation failed',
-          details: error.message
-        }
-      };
-    }
-
-    if (error.statusCode === 429) {
-      return {
-        status: 429,
-        body: {
-          success: false,
-          error: 'Rate limit exceeded',
-          retryAfter: 60
-        }
-      };
-    }
-
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: 'Internal server error',
-        retryable: true
-      }
-    };
-  }
-}
-
-function mapOrderData(data: any): any {
-  // Mapping logic
-  return data;
-}
-
-async function retryWithJitter<T>(fn: () => Promise<T>): Promise<T> {
-  // Retry implementation from earlier
-  return fn();
-}
-```
-
----
-
-## Summary
-
-### Key Takeaways
-
-1. **Categorize Errors**: Transient vs Permanent
-2. **Retry Smart**: Exponential backoff for transient errors
-3. **Fail Gracefully**: Partial success > total failure
-4. **Log Everything**: Structured logging for debugging
-5. **Monitor Metrics**: Track error rates and patterns
-6. **Plan Recovery**: Dead letter queue, compensation, rollback
-
-### Error Handling Hierarchy
-
-```
-1. Prevent errors (validation, type checking)
-   ↓
-2. Retry transient errors (exponential backoff)
-   ↓
-3. Degrade gracefully (fallback values, partial success)
-   ↓
-4. Log and monitor (structured logging, metrics)
-   ↓
-5. Queue for manual review (DLQ, error reports)
-```
-
----
-
-## Next Steps
-
-You've completed all integration patterns modules! Now explore:
-
-- [Quick Reference Guide](../integration-patterns-quick-reference.md) - Cheat sheet for all patterns
-- [Complete Examples](../examples/) - Production-ready implementations
-- [Use Cases](../../../01-TEMPLATES/) - Real-world scenarios
-
-Or dive deeper:
-- [Auto-Pagination Guide](../../../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)
-- [Resolvers Guide](../../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md)
-- [Universal Mapping Guide](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
-
----
-
-[← Back to Index](../integration-patterns-readme.md) | [Previous: Webhook Patterns →](./integration-patterns-04-webhook-patterns.md)
+# Module 5: Error Handling and Resilience
+
+> **Learning Objective:** Implement robust error handling, retry strategies, and resilience patterns for production-grade integrations.
+>
+> **Level:** Intermediate
+
+## Table of Contents
+
+1. [Why Error Handling Matters](#why-error-handling-matters)
+2. [Error Categories](#error-categories)
+3. [SDK Error Handling](#sdk-error-handling)
+4. [Retry Strategies](#retry-strategies)
+5. [Circuit Breaker Pattern](#circuit-breaker-pattern)
+6. [Graceful Degradation](#graceful-degradation)
+7. [Logging and Monitoring](#logging-and-monitoring)
+8. [Error Recovery Patterns](#error-recovery-patterns)
+9. [Production Checklist](#production-checklist)
+10. [Complete Examples](#complete-examples)
+11. [Summary](#summary)
+
+---
+
+## Why Error Handling Matters
+
+### Production Realities
+
+| Failure Type | Frequency | Impact | Recovery Time |
+|--------------|-----------|--------|---------------|
+| **Network Timeouts** | 1-5% of requests | Temporary | Seconds (retry) |
+| **API Rate Limits** | Variable | Temporary | Minutes (backoff) |
+| **Validation Errors** | 0.1-1% | Permanent | Manual fix |
+| **Service Outages** | Rare | Temporary | Minutes to hours |
+| **Bad Data** | 0.5-2% | Permanent | Manual fix |
+
+### Cost of Poor Error Handling
+
+```
+Scenario: 10,000 daily inventory updates, 1% error rate
+
+WITHOUT proper error handling:
+- 100 failed updates/day
+- No retry → permanent data loss
+- Manual investigation: 2 hours/day
+- Customer impact: Out-of-stock items shown available
+
+WITH proper error handling:
+- 100 initial failures
+- 95 recovered via retry (5 seconds)
+- 5 logged for manual review (15 minutes)
+- Customer impact: Minimal
+```
+
+### Error Handling Goals
+
+1. **Resilience**: Recover automatically from transient failures
+2. **Transparency**: Log errors with context for debugging
+3. **User Experience**: Provide meaningful error messages
+4. **Data Integrity**: Never lose data silently
+5. **Observability**: Monitor error rates and patterns
+
+---
+
+## Error Categories
+
+### 1. Transient Errors (Retryable)
+
+**Cause**: Temporary conditions that may resolve
+
+| Error Type | HTTP Status | Retry? | Backoff | Example |
+|------------|-------------|--------|---------|---------|
+| **Network Timeout** | 504 | Yes | Exponential | Request timeout |
+| **Rate Limit** | 429 | Yes | Linear | Too many requests |
+| **Service Unavailable** | 503 | Yes | Exponential | API maintenance |
+| **Server Error** | 500 | Yes | Exponential | Internal error |
+
+### 2. Permanent Errors (Non-Retryable)
+
+**Cause**: Data or configuration issues requiring manual intervention
+
+| Error Type | HTTP Status | Retry? | Action | Example |
+|------------|-------------|--------|--------|---------|
+| **Validation Error** | 400 | No | Fix data | Missing required field |
+| **Authentication** | 401 | No | Fix credentials | Invalid token |
+| **Authorization** | 403 | No | Fix permissions | Insufficient access |
+| **Not Found** | 404 | No | Check config | Invalid endpoint |
+| **Unprocessable** | 422 | No | Fix data | Invalid field value |
+
+### 3. Partial Errors (Record-Level)
+
+**Cause**: Some records fail while others succeed
+
+| Scenario | Impact | Action | Example |
+|----------|--------|--------|---------|
+| **Batch API Errors** | Some records fail | Log failed records | 98/100 succeed |
+| **Mapping Errors** | Some records skip | Log validation errors | Missing SKU |
+| **GraphQL Errors** | Some mutations fail | Log errors, continue | Duplicate ref |
+
+---
+
+## SDK Error Handling
+
+### FluentClient Error Handling
+
+The SDK automatically handles some errors:
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ /* config */ });
+
+try {
+  const result = await client.graphql({ query, variables });
+
+  // Check for GraphQL errors
+  if (result.errors && result.errors.length > 0) {
+    // Classify errors to determine retry strategy
+    const { classifyErrors } = await import('@fluentcommerce/fc-connect-sdk');
+    const classification = classifyErrors(result.errors);
+    
+    console.error('GraphQL errors:', {
+      errorCode: classification.errorCode,
+      retryable: classification.retryable,
+      action: classification.action,
+      message: classification.userMessage,
+      errors: result.errors,
+    });
+    
+    // Don't retry non-retryable errors
+    if (!classification.retryable) {
+      throw new Error(classification.userMessage);
+    }
+    
+    // result.data may still be partially populated for retryable errors
+  }
+
+} catch (error: any) {
+  // Network or authentication errors
+  console.error('Request failed:', error.message);
+
+  // Error types:
+  if (error.code === 'ECONNREFUSED') {
+    // Network error
+  } else if (error.statusCode === 401) {
+    // Authentication error
+  } else if (error.statusCode === 429) {
+    // Rate limit
+  }
+}
+```
+
+### Batch API Error Handling
+
+```typescript
+// Create job
+const job = await client.createJob({ name: 'Inventory Sync', retailerId: '2' });
+
+// Send batches
+for (const batch of batches) {
+  try {
+    await client.sendBatch(job.id, { entities: batch });
+  } catch (error: any) {
+    console.error('Batch send failed:', error.message);
+    // Log failed batch for retry
+  }
+}
+
+// Check job status
+const status = await client.getJobStatus(job.id);
+
+if (status.errorSummary && status.errorSummary.totalErrors > 0) {
+  console.warn(`Job completed with ${status.errorSummary.totalErrors} errors`);
+
+  // Get error details
+  const errors = await client.graphql({
+    query: `
+      query GetJobErrors($jobId: ID!) {
+        job(id: $jobId) {
+          batches(first: 100) {
+            edges {
+              node {
+                errors {
+                  recordRef
+                  errorType
+                  errorMessage
+                }
+              }
+            }
+          }
+        }
+      }
+    `,
+    variables: { jobId: job.id }
+  });
+
+  // Log errors for manual review
+  console.error('Batch errors:', JSON.stringify(errors, null, 2));
+}
+```
+
+### UniversalMapper Error Handling
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper(mappingConfig);
+
+const successfulRecords = [];
+const failedRecords = [];
+
+for (const record of records) {
+  const result = await mapper.map(record);
+
+  if (result.success) {
+    successfulRecords.push(result.data);
+  } else {
+    failedRecords.push({
+      record,
+      errors: result.errors
+    });
+  }
+}
+
+console.log(`Mapped ${successfulRecords.length} records, ${failedRecords.length} failures`);
+
+// Write failed records to error file
+if (failedRecords.length > 0) {
+  await fs.writeFile(
+    'mapping-errors.json',
+    JSON.stringify(failedRecords, null, 2)
+  );
+}
+```
+
+---
+
+## Retry Strategies
+
+### Pattern 1: Exponential Backoff
+
+**Best for**: Network errors, rate limits, server errors
+
+```typescript
+/**
+ * Exponential Backoff Retry
+ *
+ * Delay = initialDelay * (2 ^ attempt)
+ * Example: 1s, 2s, 4s, 8s, 16s
+ */
+
+async function exponentialBackoff<T>(
+  fn: () => Promise<T>,
+  options = {
+    maxRetries: 5,
+    initialDelay: 1000,
+    maxDelay: 30000
+  }
+): Promise<T> {
+  let lastError: Error;
+
+  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
+    try {
+      return await fn();
+
+    } catch (error: any) {
+      lastError = error;
+
+      // Don't retry permanent errors
+      if (error.statusCode && error.statusCode < 500) {
+        throw error;
+      }
+
+      if (attempt < options.maxRetries) {
+        // Calculate delay
+        const delay = Math.min(
+          options.initialDelay * Math.pow(2, attempt),
+          options.maxDelay
+        );
+
+        console.log(`Retry ${attempt + 1}/${options.maxRetries} after ${delay}ms`);
+
+        await sleep(delay);
+      }
+    }
+  }
+
+  throw lastError!;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// Usage
+const result = await exponentialBackoff(() =>
+    client.graphql({ query, variables })
+);
+```
+
+### Pattern 2: Linear Backoff (Rate Limits)
+
+**Best for**: Rate limit errors (429)
+
+```typescript
+/**
+ * Linear Backoff for Rate Limits
+ *
+ * Delay = retryAfter (from response header)
+ */
+
+async function linearBackoff<T>(
+  fn: () => Promise<T>,
+  maxRetries = 3
+): Promise<T> {
+  let lastError: Error;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+
+    } catch (error: any) {
+      lastError = error;
+
+      if (error.statusCode === 429) {
+        // Check for Retry-After header
+        const retryAfter = error.headers?.['retry-after'];
+        const delay = retryAfter ? parseInt(retryAfter) * 1000 : 60000;
+
+        console.log(`Rate limited - retry after ${delay}ms`);
+
+        await sleep(delay);
+      } else {
+        throw error; // Not a rate limit error
+      }
+    }
+  }
+
+  throw lastError!;
+}
+
+// Usage
+const result = await linearBackoff(() =>
+    client.graphql({ query, variables })
+);
+```
+
+### Pattern 3: Jittered Backoff
+
+**Best for**: High concurrency to avoid thundering herd
+
+```typescript
+/**
+ * Jittered Exponential Backoff
+ *
+ * Adds randomness to avoid synchronized retries
+ */
+
+function jitteredBackoff(attempt: number, baseDelay = 1000, maxDelay = 30000): number {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  const jitter = Math.random() * exponentialDelay * 0.3; // ±30% jitter
+  return Math.min(exponentialDelay + jitter, maxDelay);
+}
+
+async function retryWithJitter<T>(
+  fn: () => Promise<T>,
+  maxRetries = 5
+): Promise<T> {
+  let lastError: Error;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+
+    } catch (error: any) {
+      lastError = error;
+
+      if (error.statusCode && error.statusCode < 500) {
+        throw error; // Don't retry permanent errors
+      }
+
+      if (attempt < maxRetries) {
+        const delay = jitteredBackoff(attempt);
+        console.log(`Retry ${attempt + 1} after ${delay.toFixed(0)}ms`);
+        await sleep(delay);
+      }
+    }
+  }
+
+  throw lastError!;
+}
+```
+
+---
+
+## Circuit Breaker Pattern
+
+### Concept
+
+**Prevent cascading failures** by stopping requests to failing services.
+
+```
+States:
+┌─────────┐
+│ CLOSED  │  Normal operation, allow all requests
+└────┬────┘
+     │ Failure threshold reached (e.g., 5 failures)
+     ▼
+┌─────────┐
+│  OPEN   │  Block all requests, return error immediately
+└────┬────┘
+     │ Timeout elapsed (e.g., 60 seconds)
+     ▼
+┌─────────┐
+│HALF-OPEN│  Allow limited requests to test recovery
+└────┬────┘
+     │ Success → CLOSED
+     │ Failure → OPEN
+```
+
+### Implementation
+
+```typescript
+/**
+ * Circuit Breaker
+ *
+ * Prevents cascading failures by stopping requests to failing services
+ */
+
+class CircuitBreaker {
+  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
+  private failures = 0;
+  private lastFailureTime = 0;
+
+  constructor(
+    private options = {
+      failureThreshold: 5,
+      resetTimeout: 60000,
+      halfOpenRequests: 3
+    }
+  ) {}
+
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    // Check state
+    if (this.state === 'OPEN') {
+      // Check if timeout elapsed
+      if (Date.now() - this.lastFailureTime > this.options.resetTimeout) {
+        console.log('Circuit HALF-OPEN');
+        this.state = 'HALF_OPEN';
+      } else {
+        throw new Error('Circuit breaker is OPEN - blocking requests');
+      }
+    }
+
+    try {
+      const result = await fn();
+
+      // Success - reset failures
+      if (this.state === 'HALF_OPEN') {
+        console.log('Circuit CLOSED');
+        this.state = 'CLOSED';
+      }
+      this.failures = 0;
+
+      return result;
+
+    } catch (error) {
+      this.failures++;
+      this.lastFailureTime = Date.now();
+
+      if (this.failures >= this.options.failureThreshold) {
+        console.log('Circuit OPEN - failure threshold reached');
+        this.state = 'OPEN';
+      }
+
+      throw error;
+    }
+  }
+}
+
+// Usage
+const breaker = new CircuitBreaker({
+  failureThreshold: 5,
+  resetTimeout: 60000
+});
+
+try {
+  const result = await breaker.execute(() =>
+    client.graphql({ query, variables })
+  );
+} catch (error: any) {
+  if (error.message.includes('Circuit breaker is OPEN')) {
+    console.error('Service is down - circuit breaker active');
+    // Use fallback or queue for later
+  } else {
+    throw error;
+  }
+}
+```
+
+---
+
+## Graceful Degradation
+
+### Pattern 1: Fallback Values
+
+**Provide defaults** when non-critical data is unavailable.
+
+```typescript
+async function getProductDetails(sku: string): Promise<any> {
+  try {
+    const product = await client.graphql({
+      query: `query GetProduct($sku: String!) {
+        products(ref: $sku, first: 1) {
+          edges {
+            node {
+              id
+              ref
+              name
+              price
+            }
+          }
+        }
+      }`,
+      variables: { sku }
+    });
+
+    return product?.products?.edges?.[0]?.node;
+
+  } catch (error: any) {
+    console.warn(`Failed to fetch product ${sku}, using defaults`, error);
+
+    // Return fallback
+    return {
+      id: null,
+      ref: sku,
+      name: 'Product details unavailable',
+      price: 0
+    };
+  }
+}
+```
+
+### Pattern 2: Partial Failure Handling
+
+**Process successful records** even if some fail.
+
+```typescript
+async function processOrders(orders: any[]): Promise<{
+  successful: any[];
+  failed: any[];
+}> {
+  const successful = [];
+  const failed = [];
+
+  for (const order of orders) {
+    try {
+      const result = await client.graphql({
+        query: CREATE_ORDER_MUTATION,
+        variables: { input: order }
+      });
+
+      successful.push({ order, result });
+
+    } catch (error: any) {
+      console.error(`Failed to process order ${order.ref}`, error);
+
+      failed.push({ order, error: error.message });
+
+      // Continue with next order (don't throw)
+    }
+  }
+
+  console.log(`Processed ${successful.length} orders, ${failed.length} failures`);
+
+  // Write failed orders for retry
+  if (failed.length > 0) {
+    await fs.writeFile('failed-orders.json', JSON.stringify(failed, null, 2));
+  }
+
+  return { successful, failed };
+}
+```
+
+### Pattern 3: Queue for Retry
+
+**Queue failed operations** for later retry.
+
+```typescript
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+async function processWithQueue(records: any[]) {
+  const kvAdapter = new VersoriKVAdapter(openKv());
+  const stateService = new StateService(logger);
+
+  for (const record of records) {
+    try {
+      await processRecord(record);
+
+    } catch (error: any) {
+      console.error(`Failed to process record ${record.id}`, error);
+
+      // Add to retry queue
+      const queue = await stateService.getState('retry-queue') || [];
+      queue.push({
+        record,
+        error: error.message,
+        timestamp: Date.now(),
+        retryCount: 0
+      });
+      await stateService.setState('retry-queue', queue);
+    }
+  }
+}
+
+// Separate process to retry queued items
+async function retryQueue() {
+  const kvAdapter = new VersoriKVAdapter(openKv());
+  const stateService = new StateService(logger);
+
+  const queue = await stateService.getState('retry-queue') || [];
+  const remainingQueue = [];
+
+  for (const item of queue) {
+    try {
+      await processRecord(item.record);
+      console.log(`✓ Retry succeeded for ${item.record.id}`);
+
+    } catch (error: any) {
+      item.retryCount++;
+
+      if (item.retryCount < 3) {
+        // Re-queue
+        remainingQueue.push(item);
+      } else {
+        // Max retries reached - log as permanent failure
+        console.error(`✗ Max retries reached for ${item.record.id}`);
+      }
+    }
+  }
+
+  await stateService.setState('retry-queue', remainingQueue);
+}
+```
+
+---
+
+## Logging and Monitoring
+
+### Structured Logging
+
+**Use SDK logging utilities** for consistent format and easy parsing.
+
+```typescript
+import {
+  createConsoleLogger,
+  toStructuredLogger,
+  generateCorrelationId
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Basic console logger
+const logger = createConsoleLogger();
+
+// Or with structured context
+const contextLogger = toStructuredLogger(logger, {
+  service: 'InventorySync',
+  correlationId: generateCorrelationId(),
+  environment: 'production'
+});
+
+// Usage
+contextLogger.info('Processing inventory file', {
+  fileName: 'inventory.csv',
+  recordCount: 5000
+});
+// Output: [INFO] Processing inventory file
+//         {"service":"InventorySync","correlationId":"...","fileName":"inventory.csv","recordCount":5000}
+
+contextLogger.error('Batch API error', error, {
+  jobId: job.id,
+  batchId: batch.id
+});
+// Output: [ERROR] Batch API error
+//         {"service":"InventorySync","error":"...","stack":"...","jobId":"...","batchId":"..."}
+```
+
+**For Versori Platform:**
+
+```typescript
+// ✅ CORRECT - Use native log from context
+import { schedule } from '@versori/run';
+
+export const myWorkflow = schedule('workflow', '0 * * * *')
+  .execute(async ({ log }) => {
+    // Use native log directly - don't wrap it!
+    log.info('Processing started');
+    log.error('Processing failed', error);
+  });
+```
+
+### Error Metrics
+
+**Track error rates** for monitoring.
+
+```typescript
+class ErrorMetrics {
+  private errors: Map<string, number> = new Map();
+  private total = 0;
+
+  recordError(type: string) {
+    this.errors.set(type, (this.errors.get(type) || 0) + 1);
+    this.total++;
+  }
+
+  getMetrics() {
+    const metrics: any = {
+      totalErrors: this.total,
+      errorsByType: {}
+    };
+
+    for (const [type, count] of this.errors.entries()) {
+      metrics.errorsByType[type] = {
+        count,
+        percentage: ((count / this.total) * 100).toFixed(2) + '%'
+      };
+    }
+
+    return metrics;
+  }
+
+  reset() {
+    this.errors.clear();
+    this.total = 0;
+  }
+}
+
+// Usage
+const metrics = new ErrorMetrics();
+
+try {
+  await processRecord(record);
+} catch (error: any) {
+  if (error.statusCode === 429) {
+    metrics.recordError('RATE_LIMIT');
+  } else if (error.statusCode >= 500) {
+    metrics.recordError('SERVER_ERROR');
+  } else {
+    metrics.recordError('VALIDATION_ERROR');
+  }
+}
+
+// Log metrics periodically
+console.log('Error metrics:', metrics.getMetrics());
+```
+
+---
+
+## Error Recovery Patterns
+
+### Pattern 1: Dead Letter Queue
+
+**Store failed records** for manual review.
+
+```typescript
+async function processWithDLQ(records: any[]) {
+  const successCount = 0;
+  const dlq: any[] = [];
+
+  for (const record of records) {
+    try {
+      await processRecord(record);
+      successCount++;
+
+    } catch (error: any) {
+      // Add to dead letter queue
+      dlq.push({
+        record,
+        error: error.message,
+        stack: error.stack,
+        timestamp: new Date().toISOString(),
+        context: {
+          fileName: 'inventory.csv',
+          lineNumber: record._lineNumber
+        }
+      });
+    }
+  }
+
+  // Write DLQ to file
+  if (dlq.length > 0) {
+    await fs.writeFile(
+      `dlq-${Date.now()}.json`,
+      JSON.stringify(dlq, null, 2)
+    );
+
+    console.log(`Processed ${successCount} records, ${dlq.length} in DLQ`);
+  }
+}
+```
+
+### Pattern 2: Compensating Transaction
+
+**Undo partial changes** on failure.
+
+```typescript
+async function createOrderWithRollback(orderData: any) {
+  let customerId: string | null = null;
+
+  try {
+    // Step 1: Create customer
+    const customer = await client.graphql({
+      query: CREATE_CUSTOMER_MUTATION,
+      variables: { input: orderData.customer }
+    });
+    customerId = customer.id;
+
+    // Step 2: Create order
+    const order = await client.graphql({
+      query: CREATE_ORDER_MUTATION,
+      variables: {
+        input: {
+          ...orderData,
+          customer: { id: customerId }
+        }
+      }
+    });
+
+    return order;
+
+  } catch (error: any) {
+    console.error('Order creation failed', error);
+
+    // Rollback: Delete customer if created
+    if (customerId) {
+      try {
+        await client.graphql({
+          query: DELETE_CUSTOMER_MUTATION,
+          variables: { id: customerId }
+        });
+        console.log(`Rolled back customer ${customerId}`);
+      } catch (rollbackError) {
+        console.error('Rollback failed', rollbackError);
+      }
+    }
+
+    throw error;
+  }
+}
+```
+
+---
+
+## Production Checklist
+
+### Before Deployment
+
+- [ ] **Error handling** for all API calls
+- [ ] **Retry logic** for transient errors
+- [ ] **Validation** for all input data
+- [ ] **Logging** with structured format
+- [ ] **Error metrics** and monitoring
+- [ ] **Circuit breaker** for external dependencies
+- [ ] **Graceful degradation** for non-critical failures
+- [ ] **Dead letter queue** for failed records
+- [ ] **Idempotency** for duplicate prevention
+- [ ] **Timeout configuration** for all operations
+- [ ] **Rate limit handling** with backoff
+- [ ] **Security** (signature verification, IP allowlist)
+- [ ] **Health check** endpoint
+- [ ] **Error documentation** for ops team
+
+### Monitoring
+
+- [ ] **Error rate** (< 1% target)
+- [ ] **Retry rate** (< 5% target)
+- [ ] **Response time** (p50, p95, p99)
+- [ ] **Success rate** (> 99% target)
+- [ ] **DLQ size** (alert if > 100)
+- [ ] **Circuit breaker** state changes
+- [ ] **Queue depth** (for async processing)
+
+---
+
+## Complete Examples
+
+### Production-Ready Webhook with Full Error Handling
+
+```typescript
+/**
+ * Production-ready webhook with comprehensive error handling
+ */
+
+import { createClient, GraphQLMutationMapper, StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export default async function productionWebhook(activation: any, log: any, connections: any) {
+  const startTime = Date.now();
+  const webhookId = activation.headers['x-webhook-id'] || crypto.randomUUID();
+
+  try {
+    log.info('Webhook received', {
+      webhookId,
+      source: activation.headers['user-agent']
+    });
+
+    // Idempotency check
+    const kvAdapter = new VersoriKVAdapter(openKv());
+    const stateService = new StateService(logger);
+
+    const processed = await stateService.getState(`webhook:${webhookId}`);
+    if (processed) {
+      log.info('Webhook already processed', { webhookId });
+      return {
+        status: 200,
+        body: {
+          success: true,
+          message: 'Already processed',
+          orderId: processed.orderId
+        }
+      };
+    }
+
+    // Validate payload
+    if (!activation.body || !activation.body.orderRef) {
+      throw new Error('Missing required field: orderRef');
+    }
+
+    // Create client with retry
+    const client = await retryWithJitter(() =>
+      createClient({
+        connection: connections.fluent_commerce,
+        logger: log
+      })
+    );
+
+    // Process order
+    const result = await retryWithJitter(() =>
+      client.graphql({
+        query: CREATE_ORDER_MUTATION,
+        variables: { input: mapOrderData(activation.body) }
+      })
+    );
+
+    // Mark as processed
+    await stateService.setState(`webhook:${webhookId}`, {
+      orderId: result.id,
+      processedAt: new Date().toISOString()
+    });
+
+    const duration = Date.now() - startTime;
+
+    log.info('Webhook processed successfully', {
+      webhookId,
+      orderId: result.id,
+      duration
+    });
+
+    return {
+      status: 200,
+      body: {
+        success: true,
+        orderId: result.id,
+        duration
+      }
+    };
+
+  } catch (error: any) {
+    const duration = Date.now() - startTime;
+
+    log.error('Webhook processing failed', error, {
+      webhookId,
+      duration
+    });
+
+    // Categorize error
+    if (error.message.includes('required field')) {
+      return {
+        status: 400,
+        body: {
+          success: false,
+          error: 'Validation failed',
+          details: error.message
+        }
+      };
+    }
+
+    if (error.statusCode === 429) {
+      return {
+        status: 429,
+        body: {
+          success: false,
+          error: 'Rate limit exceeded',
+          retryAfter: 60
+        }
+      };
+    }
+
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: 'Internal server error',
+        retryable: true
+      }
+    };
+  }
+}
+
+function mapOrderData(data: any): any {
+  // Mapping logic
+  return data;
+}
+
+async function retryWithJitter<T>(fn: () => Promise<T>): Promise<T> {
+  // Retry implementation from earlier
+  return fn();
+}
+```
+
+---
+
+## Summary
+
+### Key Takeaways
+
+1. **Categorize Errors**: Transient vs Permanent
+2. **Retry Smart**: Exponential backoff for transient errors
+3. **Fail Gracefully**: Partial success > total failure
+4. **Log Everything**: Structured logging for debugging
+5. **Monitor Metrics**: Track error rates and patterns
+6. **Plan Recovery**: Dead letter queue, compensation, rollback
+
+### Error Handling Hierarchy
+
+```
+1. Prevent errors (validation, type checking)
+   ↓
+2. Retry transient errors (exponential backoff)
+   ↓
+3. Degrade gracefully (fallback values, partial success)
+   ↓
+4. Log and monitor (structured logging, metrics)
+   ↓
+5. Queue for manual review (DLQ, error reports)
+```
+
+---
+
+## Next Steps
+
+You've completed all integration patterns modules! Now explore:
+
+- [Quick Reference Guide](../integration-patterns-quick-reference.md) - Cheat sheet for all patterns
+- [Complete Examples](../examples/) - Production-ready implementations
+- [Use Cases](../../../01-TEMPLATES/) - Real-world scenarios
+
+Or dive deeper:
+- [Auto-Pagination Guide](../../../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)
+- [Resolvers Guide](../../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md)
+- [Universal Mapping Guide](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
+
+---
+
+[← Back to Index](../integration-patterns-readme.md) | [Previous: Webhook Patterns →](./integration-patterns-04-webhook-patterns.md)