@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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

@@ -1,527 +1,527 @@
-# Module 09: Error Handling
-
-**Level:** Intermediate
-**Category:** Error Management
-
-## Overview
-
-The SDK provides comprehensive error handling with typed error classes, error codes, and recovery patterns for building resilient integrations.
-
-## Table of Contents
-
-- [IngestionError Class](#ingestionerror-class)
-- [Error Codes](#error-codes)
-- [Error Recovery Patterns](#error-recovery-patterns)
-  - [Retry with Exponential Backoff](#retry-with-exponential-backoff)
-  - [Error Code Handling](#error-code-handling)
-  - [Job Expiration Recovery](#job-expiration-recovery)
-  - [Rate Limit Handling](#rate-limit-handling)
-- [Error Context](#error-context)
-- [Best Practices](#best-practices)
-- [See Also](#see-also)
-
----
-
-## IngestionError Class
-
-Custom error class for SDK operations with error codes and context.
-
-```typescript
-import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  await client.sendBatch(jobId, data);
-} catch (error) {
-  if (error instanceof IngestionError) {
-    switch (error.code) {
-      case IngestionErrorCode.VALIDATION_ERROR:
-        console.error('Validation failed:', error.context);
-        break;
-      case IngestionErrorCode.JOB_EXPIRED:
-        // Create new job and retry
-        break;
-      case IngestionErrorCode.RATE_LIMIT_ERROR:
-        // Implement backoff
-        break;
-    }
-  }
-}
-```
-
-**Properties:**
-- `code: IngestionErrorCode` - Error code enum for classification
-- `message: string` - Human-readable error message
-- `context?: any` - Additional context data (validation errors, API responses, etc.)
-- `cause?: Error` - Original error that caused this error (error chaining)
-
-**Constructor:**
-```typescript
-new IngestionError(
-  message: string,
-  code: IngestionErrorCode,
-  context?: any,
-  cause?: Error
-)
-```
-
-**Example with Context:**
-```typescript
-try {
-  const result = await mapper.map(data);
-  if (!result.success) {
-    throw new IngestionError(
-      'Field mapping failed',
-      IngestionErrorCode.VALIDATION_ERROR,
-      {
-        errors: result.errors,
-        failedFields: result.errors.map(e => e.field)
-      }
-    );
-  }
-} catch (error) {
-  if (error instanceof IngestionError && error.code === IngestionErrorCode.VALIDATION_ERROR) {
-    console.error('Failed fields:', error.context.failedFields);
-    error.context.errors.forEach(err => {
-      console.error(`- ${err.field}: ${err.message}`);
-    });
-  }
-}
-```
-
-## Error Codes
-
-The SDK uses typed error codes for consistent error classification:
-
-```typescript
-enum IngestionErrorCode {
-  VALIDATION_ERROR = 'VALIDATION_ERROR',
-  AUTHENTICATION_ERROR = 'AUTHENTICATION_ERROR',
-  AUTHORIZATION_ERROR = 'AUTHORIZATION_ERROR',
-  RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',
-  NETWORK_ERROR = 'NETWORK_ERROR',
-  JOB_EXPIRED = 'JOB_EXPIRED',
-  BATCH_FAILED = 'BATCH_FAILED',
-  PARSE_ERROR = 'PARSE_ERROR',
-  UNKNOWN_ERROR = 'UNKNOWN_ERROR'
-}
-```
-
-**Error Code Usage:**
-
-| Error Code | When It Occurs | Typical Recovery |
-|------------|---------------|------------------|
-| `VALIDATION_ERROR` | Invalid data, missing required fields | Fix data, review mapping config |
-| `AUTHENTICATION_ERROR` | Invalid credentials, token expired | Refresh token, check credentials |
-| `AUTHORIZATION_ERROR` | Insufficient permissions | Check user roles, API permissions |
-| `RATE_LIMIT_ERROR` | API rate limits exceeded | Implement backoff, reduce request rate |
-| `NETWORK_ERROR` | Network failure, timeout | Retry with backoff |
-| `JOB_EXPIRED` | Batch job expired (24h limit) | Create new job, resend batches |
-| `BATCH_FAILED` | Batch API rejected data | Review batch contents, check logs |
-| `PARSE_ERROR` | File parsing failed | Validate file format, check schema |
-| `UNKNOWN_ERROR` | Unexpected error | Log details, contact support |
-
-## Error Recovery Patterns
-
-### Retry with Exponential Backoff
-
-Handle transient errors with automatic retry and exponential backoff:
-
-```typescript
-async function retryWithBackoff<T>(
-  fn: () => Promise<T>,
-  maxRetries = 3,
-  initialDelayMs = 1000
-): Promise<T> {
-  let lastError: Error;
-
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error;
-
-      // Don't retry on validation errors or auth errors
-      if (error instanceof IngestionError) {
-        if (error.code === IngestionErrorCode.VALIDATION_ERROR ||
-            error.code === IngestionErrorCode.AUTHENTICATION_ERROR ||
-            error.code === IngestionErrorCode.AUTHORIZATION_ERROR) {
-          throw error; // Don't retry, fail fast
-        }
-      }
-
-      // Calculate exponential backoff delay
-      const delay = initialDelayMs * Math.pow(2, i);
-      console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms delay`);
-      await new Promise(resolve => setTimeout(resolve, delay));
-    }
-  }
-
-  throw lastError!;
-}
-
-// Usage
-const result = await retryWithBackoff(
-  () => client.sendBatch(jobId, data),
-  3,  // max retries
-  1000  // initial delay 1s (then 2s, 4s)
-);
-```
-
-### Error Code Handling
-
-Handle different error types with specific recovery strategies:
-
-```typescript
-async function handleBatchOperation(
-  client: FluentClient,
-  jobId: string,
-  data: any[]
-) {
-  try {
-    return await client.sendBatch(jobId, data);
-  } catch (error) {
-    if (!(error instanceof IngestionError)) {
-      throw error; // Re-throw non-SDK errors
-    }
-
-    switch (error.code) {
-      case IngestionErrorCode.VALIDATION_ERROR:
-        // Log validation errors and skip invalid records
-        console.error('Validation errors:', error.context);
-        return {
-          success: false,
-          errors: error.context.errors,
-          message: 'Some records failed validation'
-        };
-
-      case IngestionErrorCode.JOB_EXPIRED:
-        // Create new job and retry
-        console.warn('Job expired, creating new job');
-        const newJob = await client.createJob({
-          name: 'inventory-update-retry',
-          retailerId: client.config.retailerId
-        });
-        return await client.sendBatch(newJob.id, data);
-
-      case IngestionErrorCode.RATE_LIMIT_ERROR:
-        // Wait and retry with backoff
-        console.warn('Rate limited, waiting before retry');
-        await new Promise(resolve => setTimeout(resolve, 5000));
-        return await client.sendBatch(jobId, data);
-
-      case IngestionErrorCode.NETWORK_ERROR:
-        // Retry network errors
-        console.warn('Network error, retrying');
-        return await retryWithBackoff(() => client.sendBatch(jobId, data));
-
-      case IngestionErrorCode.AUTHENTICATION_ERROR:
-        // Retry (token refresh is automatic in v0.1.27+)
-        console.warn('Auth error, retrying with automatic token refresh');
-        return await client.sendBatch(jobId, data);
-
-      default:
-        // Log and re-throw unknown errors
-        console.error('Unexpected error:', error);
-        throw error;
-    }
-  }
-}
-```
-
-### Job Expiration Recovery
-
-Handle batch job expiration (jobs expire after 24 hours):
-
-```typescript
-import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
-
-async function sendBatchWithJobRecovery(
-  client: FluentClient,
-  jobId: string,
-  data: any[]
-) {
-  try {
-    return await client.sendBatch(jobId, data);
-  } catch (error) {
-    if (error instanceof IngestionError && error.code === IngestionErrorCode.JOB_EXPIRED) {
-      console.warn('Job expired, creating new job');
-
-      // Create new job
-      const newJob = await client.createJob({
-        name: `inventory-update-${Date.now()}`,
-        retailerId: client.config.retailerId
-      });
-
-      console.log('Created new job:', newJob.id);
-
-      // Retry with new job
-      return await client.sendBatch(newJob.id, data);
-    }
-
-    throw error;
-  }
-}
-```
-
-### Rate Limit Handling
-
-Handle API rate limits with adaptive backoff:
-
-```typescript
-async function sendBatchWithRateLimitHandling(
-  client: FluentClient,
-  jobId: string,
-  data: any[],
-  maxRetries = 5
-) {
-  let retryCount = 0;
-
-  while (retryCount < maxRetries) {
-    try {
-      return await client.sendBatch(jobId, data);
-    } catch (error) {
-      if (error instanceof IngestionError && error.code === IngestionErrorCode.RATE_LIMIT_ERROR) {
-        retryCount++;
-
-        // Exponential backoff with jitter
-        const baseDelay = 1000 * Math.pow(2, retryCount);
-        const jitter = Math.random() * 1000;
-        const delay = baseDelay + jitter;
-
-        console.warn(`Rate limited, retry ${retryCount}/${maxRetries} after ${delay}ms`);
-
-        if (retryCount >= maxRetries) {
-          throw new IngestionError(
-            `Max retries exceeded for rate limit`,
-            IngestionErrorCode.RATE_LIMIT_ERROR,
-            { retryCount, maxRetries }
-          );
-        }
-
-        await new Promise(resolve => setTimeout(resolve, delay));
-      } else {
-        throw error;
-      }
-    }
-  }
-}
-```
-
-## Error Context
-
-The `context` property provides detailed error information for debugging and recovery:
-
-### Validation Error Context
-
-```typescript
-try {
-  const result = await mapper.map(data);
-} catch (error) {
-  if (error instanceof IngestionError && error.code === IngestionErrorCode.VALIDATION_ERROR) {
-    // Context contains validation details
-    console.error('Validation errors:', error.context);
-    // {
-    //   errors: [
-    //     { field: 'productRef', message: 'Required field missing' },
-    //     { field: 'qty', message: 'Must be a number' }
-    //   ],
-    //   record: { ... },
-    //   index: 42
-    // }
-  }
-}
-```
-
-### Network Error Context
-
-```typescript
-try {
-  await client.graphql({ query, variables });
-} catch (error) {
-  if (error instanceof IngestionError && error.code === IngestionErrorCode.NETWORK_ERROR) {
-    // Context contains network details
-    console.error('Network error:', error.context);
-    // {
-    //   url: 'https://api.fluentcommerce.com/graphql',
-    //   method: 'POST',
-    //   statusCode: 503,
-    //   timeout: 30000
-    // }
-  }
-}
-```
-
-### Batch Error Context
-
-```typescript
-try {
-  await client.sendBatch(jobId, data);
-} catch (error) {
-  if (error instanceof IngestionError && error.code === IngestionErrorCode.BATCH_FAILED) {
-    // Context contains batch failure details
-    console.error('Batch failed:', error.context);
-    // {
-    //   jobId: 'job-123',
-    //   batchId: 'batch-456',
-    //   failedRecords: 23,
-    //   totalRecords: 100,
-    //   errors: [...]
-    // }
-  }
-}
-```
-
-## Best Practices
-
-### 1. Always Use Type Guards
-
-Check error types before accessing properties:
-
-```typescript
-// ✅ Correct
-try {
-  await operation();
-} catch (error) {
-  if (error instanceof IngestionError) {
-    console.error(`SDK Error [${error.code}]:`, error.message);
-    console.error('Context:', error.context);
-  } else {
-    console.error('Unknown error:', error);
-  }
-}
-
-// ❌ Wrong - assumes error type
-try {
-  await operation();
-} catch (error) {
-  console.error(error.code); // May be undefined
-}
-```
-
-### 2. Log Context for Debugging
-
-Always log error context for troubleshooting:
-
-```typescript
-catch (error) {
-  if (error instanceof IngestionError) {
-    logger.error('Operation failed', {
-      code: error.code,
-      message: error.message,
-      context: error.context,
-      cause: error.cause
-    });
-  }
-}
-```
-
-### 3. Fail Fast on Unrecoverable Errors
-
-Don't retry validation or authentication errors:
-
-```typescript
-const UNRECOVERABLE_ERRORS = [
-  IngestionErrorCode.VALIDATION_ERROR,
-  IngestionErrorCode.AUTHENTICATION_ERROR,
-  IngestionErrorCode.AUTHORIZATION_ERROR
-];
-
-async function retryableOperation() {
-  try {
-    return await operation();
-  } catch (error) {
-    if (error instanceof IngestionError &&
-        UNRECOVERABLE_ERRORS.includes(error.code)) {
-      throw error; // Fail immediately
-    }
-
-    // Retry for other errors
-    return await retryWithBackoff(() => operation());
-  }
-}
-```
-
-### 4. Use Error Chaining
-
-Preserve original errors with cause parameter:
-
-```typescript
-try {
-  const data = JSON.parse(content);
-} catch (parseError) {
-  throw new IngestionError(
-    'Failed to parse JSON content',
-    IngestionErrorCode.PARSE_ERROR,
-    { content: content.substring(0, 100) },
-    parseError  // Preserve original error
-  );
-}
-```
-
-### 5. Implement Circuit Breakers
-
-Prevent cascading failures with circuit breaker pattern:
-
-```typescript
-class CircuitBreaker {
-  private failures = 0;
-  private threshold = 5;
-  private timeout = 60000; // 1 minute
-  private isOpen = false;
-  private resetTimer?: NodeJS.Timeout;
-
-  async execute<T>(fn: () => Promise<T>): Promise<T> {
-    if (this.isOpen) {
-      throw new IngestionError(
-        'Circuit breaker is open',
-        IngestionErrorCode.NETWORK_ERROR,
-        { failures: this.failures, threshold: this.threshold }
-      );
-    }
-
-    try {
-      const result = await fn();
-      this.onSuccess();
-      return result;
-    } catch (error) {
-      this.onFailure();
-      throw error;
-    }
-  }
-
-  private onSuccess() {
-    this.failures = 0;
-  }
-
-  private onFailure() {
-    this.failures++;
-    if (this.failures >= this.threshold) {
-      this.isOpen = true;
-      this.resetTimer = setTimeout(() => {
-        this.isOpen = false;
-        this.failures = 0;
-      }, this.timeout);
-    }
-  }
-}
-
-// Usage
-const breaker = new CircuitBreaker();
-
-try {
-  const result = await breaker.execute(() => client.sendBatch(jobId, data));
-} catch (error) {
-  console.error('Operation failed:', error);
-}
-```
-
-## See Also
-
-- [Module 01: Client - Batch API](./api-reference-01-client-api.md#job-batch-operations) - Batch operation error handling
-- [Module 08: Types](./api-reference-08-types.md) - IngestionErrorCode enum
-- [Getting Started Guide](../../../00-START-HERE/getting-started.md) - Error handling basics
-- [Troubleshooting Guide](../../../00-START-HERE/troubleshooting-quick-reference.md) - Common errors and solutions
-
----
-
-**[← Previous: Module 08 - Types](./api-reference-08-types.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Module 10 - Utilities →](./api-reference-10-utilities.md)**
+# Module 09: Error Handling
+
+**Level:** Intermediate
+**Category:** Error Management
+
+## Overview
+
+The SDK provides comprehensive error handling with typed error classes, error codes, and recovery patterns for building resilient integrations.
+
+## Table of Contents
+
+- [IngestionError Class](#ingestionerror-class)
+- [Error Codes](#error-codes)
+- [Error Recovery Patterns](#error-recovery-patterns)
+  - [Retry with Exponential Backoff](#retry-with-exponential-backoff)
+  - [Error Code Handling](#error-code-handling)
+  - [Job Expiration Recovery](#job-expiration-recovery)
+  - [Rate Limit Handling](#rate-limit-handling)
+- [Error Context](#error-context)
+- [Best Practices](#best-practices)
+- [See Also](#see-also)
+
+---
+
+## IngestionError Class
+
+Custom error class for SDK operations with error codes and context.
+
+```typescript
+import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  await client.sendBatch(jobId, data);
+} catch (error) {
+  if (error instanceof IngestionError) {
+    switch (error.code) {
+      case IngestionErrorCode.VALIDATION_ERROR:
+        console.error('Validation failed:', error.context);
+        break;
+      case IngestionErrorCode.JOB_EXPIRED:
+        // Create new job and retry
+        break;
+      case IngestionErrorCode.RATE_LIMIT_ERROR:
+        // Implement backoff
+        break;
+    }
+  }
+}
+```
+
+**Properties:**
+- `code: IngestionErrorCode` - Error code enum for classification
+- `message: string` - Human-readable error message
+- `context?: any` - Additional context data (validation errors, API responses, etc.)
+- `cause?: Error` - Original error that caused this error (error chaining)
+
+**Constructor:**
+```typescript
+new IngestionError(
+  message: string,
+  code: IngestionErrorCode,
+  context?: any,
+  cause?: Error
+)
+```
+
+**Example with Context:**
+```typescript
+try {
+  const result = await mapper.map(data);
+  if (!result.success) {
+    throw new IngestionError(
+      'Field mapping failed',
+      IngestionErrorCode.VALIDATION_ERROR,
+      {
+        errors: result.errors,
+        failedFields: result.errors.map(e => e.field)
+      }
+    );
+  }
+} catch (error) {
+  if (error instanceof IngestionError && error.code === IngestionErrorCode.VALIDATION_ERROR) {
+    console.error('Failed fields:', error.context.failedFields);
+    error.context.errors.forEach(err => {
+      console.error(`- ${err.field}: ${err.message}`);
+    });
+  }
+}
+```
+
+## Error Codes
+
+The SDK uses typed error codes for consistent error classification:
+
+```typescript
+enum IngestionErrorCode {
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  AUTHENTICATION_ERROR = 'AUTHENTICATION_ERROR',
+  AUTHORIZATION_ERROR = 'AUTHORIZATION_ERROR',
+  RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  JOB_EXPIRED = 'JOB_EXPIRED',
+  BATCH_FAILED = 'BATCH_FAILED',
+  PARSE_ERROR = 'PARSE_ERROR',
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR'
+}
+```
+
+**Error Code Usage:**
+
+| Error Code | When It Occurs | Typical Recovery |
+|------------|---------------|------------------|
+| `VALIDATION_ERROR` | Invalid data, missing required fields | Fix data, review mapping config |
+| `AUTHENTICATION_ERROR` | Invalid credentials, token expired | Refresh token, check credentials |
+| `AUTHORIZATION_ERROR` | Insufficient permissions | Check user roles, API permissions |
+| `RATE_LIMIT_ERROR` | API rate limits exceeded | Implement backoff, reduce request rate |
+| `NETWORK_ERROR` | Network failure, timeout | Retry with backoff |
+| `JOB_EXPIRED` | Batch job expired (24h limit) | Create new job, resend batches |
+| `BATCH_FAILED` | Batch API rejected data | Review batch contents, check logs |
+| `PARSE_ERROR` | File parsing failed | Validate file format, check schema |
+| `UNKNOWN_ERROR` | Unexpected error | Log details, contact support |
+
+## Error Recovery Patterns
+
+### Retry with Exponential Backoff
+
+Handle transient errors with automatic retry and exponential backoff:
+
+```typescript
+async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  maxRetries = 3,
+  initialDelayMs = 1000
+): Promise<T> {
+  let lastError: Error;
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      // Don't retry on validation errors or auth errors
+      if (error instanceof IngestionError) {
+        if (error.code === IngestionErrorCode.VALIDATION_ERROR ||
+            error.code === IngestionErrorCode.AUTHENTICATION_ERROR ||
+            error.code === IngestionErrorCode.AUTHORIZATION_ERROR) {
+          throw error; // Don't retry, fail fast
+        }
+      }
+
+      // Calculate exponential backoff delay
+      const delay = initialDelayMs * Math.pow(2, i);
+      console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms delay`);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError!;
+}
+
+// Usage
+const result = await retryWithBackoff(
+  () => client.sendBatch(jobId, data),
+  3,  // max retries
+  1000  // initial delay 1s (then 2s, 4s)
+);
+```
+
+### Error Code Handling
+
+Handle different error types with specific recovery strategies:
+
+```typescript
+async function handleBatchOperation(
+  client: FluentClient,
+  jobId: string,
+  data: any[]
+) {
+  try {
+    return await client.sendBatch(jobId, data);
+  } catch (error) {
+    if (!(error instanceof IngestionError)) {
+      throw error; // Re-throw non-SDK errors
+    }
+
+    switch (error.code) {
+      case IngestionErrorCode.VALIDATION_ERROR:
+        // Log validation errors and skip invalid records
+        console.error('Validation errors:', error.context);
+        return {
+          success: false,
+          errors: error.context.errors,
+          message: 'Some records failed validation'
+        };
+
+      case IngestionErrorCode.JOB_EXPIRED:
+        // Create new job and retry
+        console.warn('Job expired, creating new job');
+        const newJob = await client.createJob({
+          name: 'inventory-update-retry',
+          retailerId: client.config.retailerId
+        });
+        return await client.sendBatch(newJob.id, data);
+
+      case IngestionErrorCode.RATE_LIMIT_ERROR:
+        // Wait and retry with backoff
+        console.warn('Rate limited, waiting before retry');
+        await new Promise(resolve => setTimeout(resolve, 5000));
+        return await client.sendBatch(jobId, data);
+
+      case IngestionErrorCode.NETWORK_ERROR:
+        // Retry network errors
+        console.warn('Network error, retrying');
+        return await retryWithBackoff(() => client.sendBatch(jobId, data));
+
+      case IngestionErrorCode.AUTHENTICATION_ERROR:
+        // Retry (token refresh is automatic in v0.1.27+)
+        console.warn('Auth error, retrying with automatic token refresh');
+        return await client.sendBatch(jobId, data);
+
+      default:
+        // Log and re-throw unknown errors
+        console.error('Unexpected error:', error);
+        throw error;
+    }
+  }
+}
+```
+
+### Job Expiration Recovery
+
+Handle batch job expiration (jobs expire after 24 hours):
+
+```typescript
+import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
+
+async function sendBatchWithJobRecovery(
+  client: FluentClient,
+  jobId: string,
+  data: any[]
+) {
+  try {
+    return await client.sendBatch(jobId, data);
+  } catch (error) {
+    if (error instanceof IngestionError && error.code === IngestionErrorCode.JOB_EXPIRED) {
+      console.warn('Job expired, creating new job');
+
+      // Create new job
+      const newJob = await client.createJob({
+        name: `inventory-update-${Date.now()}`,
+        retailerId: client.config.retailerId
+      });
+
+      console.log('Created new job:', newJob.id);
+
+      // Retry with new job
+      return await client.sendBatch(newJob.id, data);
+    }
+
+    throw error;
+  }
+}
+```
+
+### Rate Limit Handling
+
+Handle API rate limits with adaptive backoff:
+
+```typescript
+async function sendBatchWithRateLimitHandling(
+  client: FluentClient,
+  jobId: string,
+  data: any[],
+  maxRetries = 5
+) {
+  let retryCount = 0;
+
+  while (retryCount < maxRetries) {
+    try {
+      return await client.sendBatch(jobId, data);
+    } catch (error) {
+      if (error instanceof IngestionError && error.code === IngestionErrorCode.RATE_LIMIT_ERROR) {
+        retryCount++;
+
+        // Exponential backoff with jitter
+        const baseDelay = 1000 * Math.pow(2, retryCount);
+        const jitter = Math.random() * 1000;
+        const delay = baseDelay + jitter;
+
+        console.warn(`Rate limited, retry ${retryCount}/${maxRetries} after ${delay}ms`);
+
+        if (retryCount >= maxRetries) {
+          throw new IngestionError(
+            `Max retries exceeded for rate limit`,
+            IngestionErrorCode.RATE_LIMIT_ERROR,
+            { retryCount, maxRetries }
+          );
+        }
+
+        await new Promise(resolve => setTimeout(resolve, delay));
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+```
+
+## Error Context
+
+The `context` property provides detailed error information for debugging and recovery:
+
+### Validation Error Context
+
+```typescript
+try {
+  const result = await mapper.map(data);
+} catch (error) {
+  if (error instanceof IngestionError && error.code === IngestionErrorCode.VALIDATION_ERROR) {
+    // Context contains validation details
+    console.error('Validation errors:', error.context);
+    // {
+    //   errors: [
+    //     { field: 'productRef', message: 'Required field missing' },
+    //     { field: 'qty', message: 'Must be a number' }
+    //   ],
+    //   record: { ... },
+    //   index: 42
+    // }
+  }
+}
+```
+
+### Network Error Context
+
+```typescript
+try {
+  await client.graphql({ query, variables });
+} catch (error) {
+  if (error instanceof IngestionError && error.code === IngestionErrorCode.NETWORK_ERROR) {
+    // Context contains network details
+    console.error('Network error:', error.context);
+    // {
+    //   url: 'https://api.fluentcommerce.com/graphql',
+    //   method: 'POST',
+    //   statusCode: 503,
+    //   timeout: 30000
+    // }
+  }
+}
+```
+
+### Batch Error Context
+
+```typescript
+try {
+  await client.sendBatch(jobId, data);
+} catch (error) {
+  if (error instanceof IngestionError && error.code === IngestionErrorCode.BATCH_FAILED) {
+    // Context contains batch failure details
+    console.error('Batch failed:', error.context);
+    // {
+    //   jobId: 'job-123',
+    //   batchId: 'batch-456',
+    //   failedRecords: 23,
+    //   totalRecords: 100,
+    //   errors: [...]
+    // }
+  }
+}
+```
+
+## Best Practices
+
+### 1. Always Use Type Guards
+
+Check error types before accessing properties:
+
+```typescript
+// ✅ Correct
+try {
+  await operation();
+} catch (error) {
+  if (error instanceof IngestionError) {
+    console.error(`SDK Error [${error.code}]:`, error.message);
+    console.error('Context:', error.context);
+  } else {
+    console.error('Unknown error:', error);
+  }
+}
+
+// ❌ Wrong - assumes error type
+try {
+  await operation();
+} catch (error) {
+  console.error(error.code); // May be undefined
+}
+```
+
+### 2. Log Context for Debugging
+
+Always log error context for troubleshooting:
+
+```typescript
+catch (error) {
+  if (error instanceof IngestionError) {
+    logger.error('Operation failed', {
+      code: error.code,
+      message: error.message,
+      context: error.context,
+      cause: error.cause
+    });
+  }
+}
+```
+
+### 3. Fail Fast on Unrecoverable Errors
+
+Don't retry validation or authentication errors:
+
+```typescript
+const UNRECOVERABLE_ERRORS = [
+  IngestionErrorCode.VALIDATION_ERROR,
+  IngestionErrorCode.AUTHENTICATION_ERROR,
+  IngestionErrorCode.AUTHORIZATION_ERROR
+];
+
+async function retryableOperation() {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof IngestionError &&
+        UNRECOVERABLE_ERRORS.includes(error.code)) {
+      throw error; // Fail immediately
+    }
+
+    // Retry for other errors
+    return await retryWithBackoff(() => operation());
+  }
+}
+```
+
+### 4. Use Error Chaining
+
+Preserve original errors with cause parameter:
+
+```typescript
+try {
+  const data = JSON.parse(content);
+} catch (parseError) {
+  throw new IngestionError(
+    'Failed to parse JSON content',
+    IngestionErrorCode.PARSE_ERROR,
+    { content: content.substring(0, 100) },
+    parseError  // Preserve original error
+  );
+}
+```
+
+### 5. Implement Circuit Breakers
+
+Prevent cascading failures with circuit breaker pattern:
+
+```typescript
+class CircuitBreaker {
+  private failures = 0;
+  private threshold = 5;
+  private timeout = 60000; // 1 minute
+  private isOpen = false;
+  private resetTimer?: NodeJS.Timeout;
+
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.isOpen) {
+      throw new IngestionError(
+        'Circuit breaker is open',
+        IngestionErrorCode.NETWORK_ERROR,
+        { failures: this.failures, threshold: this.threshold }
+      );
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+
+  private onSuccess() {
+    this.failures = 0;
+  }
+
+  private onFailure() {
+    this.failures++;
+    if (this.failures >= this.threshold) {
+      this.isOpen = true;
+      this.resetTimer = setTimeout(() => {
+        this.isOpen = false;
+        this.failures = 0;
+      }, this.timeout);
+    }
+  }
+}
+
+// Usage
+const breaker = new CircuitBreaker();
+
+try {
+  const result = await breaker.execute(() => client.sendBatch(jobId, data));
+} catch (error) {
+  console.error('Operation failed:', error);
+}
+```
+
+## See Also
+
+- [Module 01: Client - Batch API](./api-reference-01-client-api.md#job-batch-operations) - Batch operation error handling
+- [Module 08: Types](./api-reference-08-types.md) - IngestionErrorCode enum
+- [Getting Started Guide](../../../00-START-HERE/getting-started.md) - Error handling basics
+- [Troubleshooting Guide](../../../00-START-HERE/troubleshooting-quick-reference.md) - Common errors and solutions
+
+---
+
+**[← Previous: Module 08 - Types](./api-reference-08-types.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Module 10 - Utilities →](./api-reference-10-utilities.md)**