@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-04-error-scenarios.md

@@ -1,658 +1,658 @@
-# Module 4: Error Scenarios
-
-**Level:** Intermediate
-**Estimated Time:** 25 minutes
-
-## Overview
-
-This module presents real-world error scenarios with complete examples showing the error, the outcome, and the impact on data in Fluent Commerce.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Recognize common error scenarios and their causes
-- ✅ Understand the exact outcome for each error type
-- ✅ Know whether mutations are executed for each scenario
-- ✅ Learn how to diagnose errors from error messages
-
-## Scenario 1: Wrong Source Path
-
-### The Problem
-
-Mapping configuration references a field path that doesn't exist in the source data.
-
-### Mapping Configuration
-
-```json
-{
-  "ref": {
-    "source": "order.WRONG_PATH.customer-email",
-    "required": true
-  }
-}
-```
-
-### Source Data
-
-```json
-{
-  "order": {
-    "customer": {
-      "email": "test@example.com"  // Actual path: order.customer.email
-    }
-  }
-}
-```
-
-### Error Result
-
-```typescript
-PathResolutionError: Cannot resolve path 'order.WRONG_PATH.customer-email'
-  path: "order.WRONG_PATH.customer-email"
-  cause: undefined
-```
-
-### Impact
-
-✅ Mutation **NEVER EXECUTED** - No data created in Fluent
-
-### How to Fix
-
-```json
-{
-  "ref": {
-    "source": "order.customer.email",  // ✅ Correct path
-    "required": true
-  }
-}
-```
-
-## Scenario 2: Missing Required Field
-
-### The Problem
-
-Source data doesn't contain a required field, or the field is empty.
-
-### Mapping Configuration
-
-```json
-{
-  "ref": {
-    "source": "order.customerRef",
-    "required": true
-  }
-}
-```
-
-### Source Data
-
-```json
-{
-  "order": {
-    "customerRef": null  // ❌ Required field is null
-  }
-}
-```
-
-### Error Result
-
-```typescript
-MappingError: Required field 'ref' is missing or empty
-  field: "ref"
-  sourcePath: "order.customerRef"
-```
-
-### Impact
-
-✅ Mutation **NEVER EXECUTED** - No data created in Fluent
-
-### How to Fix
-
-**Option 1: Fix source data**
-```json
-{
-  "order": {
-    "customerRef": "CUST-12345"  // ✅ Provide value
-  }
-}
-```
-
-**Option 2: Make field optional**
-```json
-{
-  "ref": {
-    "source": "order.customerRef",
-    "required": false  // ✅ Optional
-  }
-}
-```
-
-**Option 3: Provide default value**
-```json
-{
-  "ref": {
-    "source": "order.customerRef",
-    "defaultValue": "GUEST",  // ✅ Fallback
-    "required": true
-  }
-}
-```
-
-## Scenario 3: Wrong GraphQL Target Field
-
-### The Problem
-
-Mapping generates a GraphQL mutation with a field that doesn't exist in the schema.
-
-### Mapping Configuration
-
-```json
-{
-  "mutation": "createOrder",
-  "arguments": {
-    "input": {
-      "INVALID_FIELD": {
-        "source": "order.value"
-      }
-    }
-  }
-}
-```
-
-### Generated Mutation
-
-```graphql
-mutation CreateOrder($input: CreateOrderInput!) {
-  createOrder(input: $input) {
-    id
-  }
-}
-
-# Variables
-{
-  "input": {
-    "INVALID_FIELD": "123"  # ❌ Not in GraphQL schema
-  }
-}
-```
-
-### Error Result
-```typescript
-GraphQLExecutionError {
-  name: "GraphQLExecutionError",
-  message: "Field 'INVALID_FIELD' doesn't exist on type 'CreateOrderInput'",
-  graphqlErrors: [
-    {
-      message: "Field 'INVALID_FIELD' doesn't exist on type 'CreateOrderInput'",
-      extensions: { "code": "GRAPHQL_VALIDATION_FAILED" }
-    }
-  ]
-}
-```
-
-### Impact
-
-✅ Fluent **REJECTS** mutation - No data created (mutation sent but schema validation failed)
-
-### How to Fix
-
-1. **Introspect schema** to find correct field names:
-```bash
-npx @fluentcommerce/fc-connect-sdk introspect-schema \
-  --url https://api.fluentcommerce.com/graphql \
-  --output schema.json
-```
-
-2. **Validate mapping** against schema:
-```bash
-npx @fluentcommerce/fc-connect-sdk validate-schema \
-  --mapping mappings/order.json \
-  --schema schema.json
-```
-
-3. **Use correct field name:**
-```json
-{
-  "mutation": "createOrder",
-  "arguments": {
-    "input": {
-      "ref": {  // ✅ Valid schema field
-        "source": "order.value"
-      }
-    }
-  }
-}
-```
-
-## Scenario 4: Type Mismatch
-
-### The Problem
-
-Resolver produces a value that doesn't match the expected GraphQL type.
-
-### Mapping Configuration
-
-```json
-{
-  "quantity": {
-    "source": "quantity",
-    "resolver": "sdk.parseInt"
-  }
-}
-```
-
-### Source Data
-
-```json
-{
-  "quantity": "abc"  // ❌ Cannot parse as integer
-}
-```
-
-### Transformation Result
-
-```typescript
-parseInt("abc") = NaN  // ❌ Not a number
-```
-
-### Error Result
-```typescript
-GraphQLExecutionError {
-  name: "GraphQLExecutionError",
-  message: "Expected type Int!, found NaN",
-  graphqlErrors: [
-    {
-      message: "Expected type Int!, found NaN",
-      path: ["createInventoryPosition", "input", "quantity"],
-      extensions: { "code": "BAD_USER_INPUT" }
-    }
-  ]
-}
-```
-
-### Impact
-
-✅ Fluent **REJECTS** mutation - No data created
-
-### How to Fix
-
-**Option 1: Validate and provide default**
-```json
-{
-  "quantity": {
-    "source": "quantity",
-    "resolver": "sdk.parseInt",
-    "defaultValue": 0  // ✅ Fallback for NaN
-  }
-}
-```
-
-**Option 2: Custom resolver with validation**
-```typescript
-const customResolvers = {
-  'custom.parseIntSafe': (value: any) => {
-    const parsed = parseInt(value, 10);
-    if (isNaN(parsed)) {
-      throw new Error(`Cannot parse '${value}' as integer`);
-    }
-    return parsed;
-  }
-};
-```
-
-## Scenario 5: Array Validation Failure
-
-### The Problem
-
-Array doesn't meet validation constraints (minItems, maxItems).
-
-### Mapping Configuration
-
-```json
-{
-  "items": {
-    "_array": true,
-    "_validation": {
-      "minItems": 1,
-      "maxItems": 100
-    },
-    "source": "product-lineitems.product-lineitem"
-  }
-}
-```
-
-### Source Data - Empty Array
-
-```json
-{
-  "product-lineitems": {
-    "product-lineitem": []  // ❌ Empty array, minItems is 1
-  }
-}
-```
-
-### Error Result
-
-```typescript
-MappingError: Array must have at least 1 items, got 0
-  field: "items"
-  sourcePath: "product-lineitems.product-lineitem"
-```
-
-### Impact
-
-✅ Mutation **NEVER EXECUTED** - No data created
-
-### How to Fix
-
-**Option 1: Ensure source has items**
-```json
-{
-  "product-lineitems": {
-    "product-lineitem": [
-      { "ref": "ITEM-001" }  // ✅ At least one item
-    ]
-  }
-}
-```
-
-**Option 2: Adjust validation**
-```json
-{
-  "items": {
-    "_array": true,
-    "_validation": {
-      "minItems": 0  // ✅ Allow empty arrays
-    },
-    "source": "product-lineitems.product-lineitem"
-  }
-}
-```
-
-## Scenario 6: Invalid XML
-
-### The Problem
-
-Source file is malformed and cannot be parsed.
-
-### Input XML
-
-```xml
-<order>
-  <customer-email>test@example.com
-  <!-- ❌ Missing closing tag for customer-email and order -->
-```
-
-### Error Result
-
-```typescript
-FileParsingError: Failed to parse XML: Unclosed tag 'customer-email'
-  fileName: "order.xml"
-  lineNumber: 2
-  code: "PARSE_ERROR"
-  context: {
-    originalError: SyntaxError("Unclosed tag 'customer-email'")
-  }
-```
-
-### Impact
-
-✅ Mutation **NEVER ATTEMPTED** - No data created (parsing failed before mapping)
-
-### How to Fix
-
-Fix the XML syntax:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<order>
-  <customer-email>test@example.com</customer-email>  <!-- ✅ Properly closed -->
-</order>
-```
-
-## Scenario 7: Invalid JSON
-
-### The Problem
-
-JSON syntax is invalid.
-
-### Input JSON
-
-```json
-{
-  "order": {
-    "ref": "ORDER-123",
-    "status": active  // ❌ Unquoted string value
-  }
-}
-```
-
-### Error Result
-
-```typescript
-FileParsingError: Failed to parse JSON: Unexpected token a in JSON at position 45
-  fileName: "order.json"
-  code: "PARSE_ERROR"
-  context: {
-    originalError: SyntaxError("Unexpected token a...")
-  }
-```
-
-### Impact
-
-✅ Mutation **NEVER ATTEMPTED** - No data created
-
-### How to Fix
-
-Quote string values:
-
-```json
-{
-  "order": {
-    "ref": "ORDER-123",
-    "status": "active"  // ✅ Quoted string
-  }
-}
-```
-
-## Scenario 8: UTF-8 Encoding Issue
-
-### The Problem
-
-File contains invalid UTF-8 sequences or special characters that aren't handled.
-
-### Input (Binary representation)
-
-```
-0xFF 0xFE <order>...  // ❌ BOM (Byte Order Mark) at start
-```
-
-### What Happens
-
-The SDK automatically handles UTF-8 BOMs:
-
-```typescript
-// XMLParserService preprocessing
-private preprocessXML(xmlContent: string): string {
-  // Remove BOM (Byte Order Mark) if present
-  let cleaned = xmlContent.replace(/^\uFEFF/, '');  // ✅ BOM removed
-  return cleaned;
-}
-```
-
-### Result
-
-✅ **No error** - BOM is automatically removed and parsing succeeds
-
-### Supported Characters
-
-All UTF-8 characters are supported:
-
-```xml
-<order>
-  <customer>
-    <name>José García</name>
-    <email>josé@example.com</email>
-    <notes>Special chars: &amp; &lt; &gt; &quot; &apos; 中文 🎉</notes>
-  </customer>
-</order>
-```
-
-✅ **Result:** Parses correctly, all characters preserved
-
-## Scenario 9: Network Timeout
-### The Problem
-API request times out or network connection fails.
-
-### Error Result
-```typescript
-// FluentClient throws FluentAPIError for 5xx, or standard Error for network
-Error: network timeout at: https://api.fluentcommerce.com/graphql
-// OR
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 503",
-  statusCode: 503,
-  details: "Service Unavailable"
-}
-```
-
-### Impact
-❓ **Unknown** - Mutation may or may not have been created (network failure)
-
-### How to Handle
-Retry with exponential backoff. The SDK's `FluentClient` automatically retries 5xx errors and 401s. For network timeouts (which throw standard `Error`), you should implement retry logic:
-
-```typescript
-import { FluentAPIError } from '@fluentcommerce/fc-connect-sdk';
-
-async function executeWithRetry(operation: () => Promise<any>, maxRetries = 3) {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      return await operation();
-    } catch (error) {
-      // Retry 5xx or network errors
-      const isRetryable = (error instanceof FluentAPIError && error.statusCode >= 500) ||
-                          error.message.includes('network') ||
-                          error.message.includes('timeout');
-
-      if (isRetryable && attempt < maxRetries) {
-        const delay = Math.pow(2, attempt) * 1000;
-        console.log(`Transient error - retrying in ${delay}ms...`);
-        await new Promise(resolve => setTimeout(resolve, delay));
-        continue;
-      }
-      throw error;
-    }
-  }
-}
-```
-
-## Scenario 10: Rate Limit Exceeded
-
-### The Problem
-Too many API requests in short time period (HTTP 429).
-
-### Error Result
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 429",
-  statusCode: 429,
-  details: "Too Many Requests"
-}
-```
-
-### Impact
-✅ Mutation **NOT EXECUTED** - Rate limit hit before processing
-
-### How to Handle
-Check `statusCode === 429` and retry with backoff:
-
-```typescript
-import { FluentAPIError } from '@fluentcommerce/fc-connect-sdk';
-
-async function handleRateLimit(operation: () => Promise<any>) {
-  try {
-    return await operation();
-  } catch (error) {
-    if (error instanceof FluentAPIError && error.statusCode === 429) {
-      console.log('Rate limit hit - waiting 60s...');
-      await new Promise(resolve => setTimeout(resolve, 60000));
-      return handleRateLimit(operation); // Retry
-    }
-    throw error;
-  }
-}
-```
-
-## Summary Table
-
-| Scenario | Error Class | Mutation Sent? | Data Created? | Retryable? |
-|----------|-------------|----------------|---------------|------------|
-| Wrong source path | `PathResolutionError` | ❌ No | ❌ No | ❌ No |
-| Missing required field | `MappingError` | ❌ No | ❌ No | ❌ No |
-| Wrong GraphQL field | `GraphQLExecutionError` | ✅ Yes | ❌ No | ❌ No |
-| Type mismatch | `GraphQLExecutionError` | ✅ Yes | ❌ No | ❌ No |
-| Array validation | `MappingError` | ❌ No | ❌ No | ❌ No |
-| Invalid XML | `FileParsingError` | ❌ No | ❌ No | ❌ No |
-| Invalid JSON | `FileParsingError` | ❌ No | ❌ No | ❌ No |
-| UTF-8 BOM | None (handled) | ✅ Yes | ✅ Yes | N/A |
-| Network timeout | `FluentAPIError` (5xx) or Error | ❓ Maybe | ❓ Maybe | ✅ Yes |
-| Rate limit | `FluentAPIError` (429) | ❌ No | ❌ No | ✅ Yes |
-
-## Key Takeaways
-
-- 🎯 **Parsing errors** prevent mutations from being sent (fail-fast)
-- 🎯 **Mapping errors** prevent mutations from being sent (fail-fast)
-- 🎯 **GraphQL errors** mean mutation was sent but rejected by Fluent
-- 🎯 **Network errors** are retryable - implement exponential backoff
-- 🎯 **Rate limits** are retryable - respect `retryAfter` value
-- 🎯 **UTF-8 handling** is automatic - BOM removal, special character support
-
-## Practice Exercise
-
-For each scenario, determine:
-1. Is the error retryable?
-2. Was the mutation sent to Fluent?
-3. What's the correct fix?
-
-**Scenarios:**
-1. XML file missing closing tag
-2. Network timeout during API call
-3. Required field is empty string
-4. Rate limit exceeded
-
-<details>
-<summary>Click to see answers</summary>
-
-1. **XML parsing error**
-   - Retryable? ❌ No
-   - Mutation sent? ❌ No
-   - Fix: Correct XML syntax
-
-2. **Network timeout**
-   - Retryable? ✅ Yes
-   - Mutation sent? ❓ Maybe (unknown state)
-   - Fix: Retry with exponential backoff
-
-3. **Empty required field**
-   - Retryable? ❌ No
-   - Mutation sent? ❌ No
-   - Fix: Provide value or make optional
-
-4. **Rate limit**
-   - Retryable? ✅ Yes
-   - Mutation sent? ❌ No
-   - Fix: Wait `retryAfter` seconds and retry
-
-</details>
-
-## Next Steps
-
-Continue to [Module 5: Calling Patterns →](./error-handling-05-calling-patterns.md) to learn code patterns for handling these errors effectively.
-
----
-
-**Previous:** [← Module 3: UTF-8 Handling](./error-handling-03-utf8-handling.md)
-**Next:** [Module 5: Calling Patterns →](./error-handling-05-calling-patterns.md)
+# Module 4: Error Scenarios
+
+**Level:** Intermediate
+**Estimated Time:** 25 minutes
+
+## Overview
+
+This module presents real-world error scenarios with complete examples showing the error, the outcome, and the impact on data in Fluent Commerce.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Recognize common error scenarios and their causes
+- ✅ Understand the exact outcome for each error type
+- ✅ Know whether mutations are executed for each scenario
+- ✅ Learn how to diagnose errors from error messages
+
+## Scenario 1: Wrong Source Path
+
+### The Problem
+
+Mapping configuration references a field path that doesn't exist in the source data.
+
+### Mapping Configuration
+
+```json
+{
+  "ref": {
+    "source": "order.WRONG_PATH.customer-email",
+    "required": true
+  }
+}
+```
+
+### Source Data
+
+```json
+{
+  "order": {
+    "customer": {
+      "email": "test@example.com"  // Actual path: order.customer.email
+    }
+  }
+}
+```
+
+### Error Result
+
+```typescript
+PathResolutionError: Cannot resolve path 'order.WRONG_PATH.customer-email'
+  path: "order.WRONG_PATH.customer-email"
+  cause: undefined
+```
+
+### Impact
+
+✅ Mutation **NEVER EXECUTED** - No data created in Fluent
+
+### How to Fix
+
+```json
+{
+  "ref": {
+    "source": "order.customer.email",  // ✅ Correct path
+    "required": true
+  }
+}
+```
+
+## Scenario 2: Missing Required Field
+
+### The Problem
+
+Source data doesn't contain a required field, or the field is empty.
+
+### Mapping Configuration
+
+```json
+{
+  "ref": {
+    "source": "order.customerRef",
+    "required": true
+  }
+}
+```
+
+### Source Data
+
+```json
+{
+  "order": {
+    "customerRef": null  // ❌ Required field is null
+  }
+}
+```
+
+### Error Result
+
+```typescript
+MappingError: Required field 'ref' is missing or empty
+  field: "ref"
+  sourcePath: "order.customerRef"
+```
+
+### Impact
+
+✅ Mutation **NEVER EXECUTED** - No data created in Fluent
+
+### How to Fix
+
+**Option 1: Fix source data**
+```json
+{
+  "order": {
+    "customerRef": "CUST-12345"  // ✅ Provide value
+  }
+}
+```
+
+**Option 2: Make field optional**
+```json
+{
+  "ref": {
+    "source": "order.customerRef",
+    "required": false  // ✅ Optional
+  }
+}
+```
+
+**Option 3: Provide default value**
+```json
+{
+  "ref": {
+    "source": "order.customerRef",
+    "defaultValue": "GUEST",  // ✅ Fallback
+    "required": true
+  }
+}
+```
+
+## Scenario 3: Wrong GraphQL Target Field
+
+### The Problem
+
+Mapping generates a GraphQL mutation with a field that doesn't exist in the schema.
+
+### Mapping Configuration
+
+```json
+{
+  "mutation": "createOrder",
+  "arguments": {
+    "input": {
+      "INVALID_FIELD": {
+        "source": "order.value"
+      }
+    }
+  }
+}
+```
+
+### Generated Mutation
+
+```graphql
+mutation CreateOrder($input: CreateOrderInput!) {
+  createOrder(input: $input) {
+    id
+  }
+}
+
+# Variables
+{
+  "input": {
+    "INVALID_FIELD": "123"  # ❌ Not in GraphQL schema
+  }
+}
+```
+
+### Error Result
+```typescript
+GraphQLExecutionError {
+  name: "GraphQLExecutionError",
+  message: "Field 'INVALID_FIELD' doesn't exist on type 'CreateOrderInput'",
+  graphqlErrors: [
+    {
+      message: "Field 'INVALID_FIELD' doesn't exist on type 'CreateOrderInput'",
+      extensions: { "code": "GRAPHQL_VALIDATION_FAILED" }
+    }
+  ]
+}
+```
+
+### Impact
+
+✅ Fluent **REJECTS** mutation - No data created (mutation sent but schema validation failed)
+
+### How to Fix
+
+1. **Introspect schema** to find correct field names:
+```bash
+npx @fluentcommerce/fc-connect-sdk introspect-schema \
+  --url https://api.fluentcommerce.com/graphql \
+  --output schema.json
+```
+
+2. **Validate mapping** against schema:
+```bash
+npx @fluentcommerce/fc-connect-sdk validate-schema \
+  --mapping mappings/order.json \
+  --schema schema.json
+```
+
+3. **Use correct field name:**
+```json
+{
+  "mutation": "createOrder",
+  "arguments": {
+    "input": {
+      "ref": {  // ✅ Valid schema field
+        "source": "order.value"
+      }
+    }
+  }
+}
+```
+
+## Scenario 4: Type Mismatch
+
+### The Problem
+
+Resolver produces a value that doesn't match the expected GraphQL type.
+
+### Mapping Configuration
+
+```json
+{
+  "quantity": {
+    "source": "quantity",
+    "resolver": "sdk.parseInt"
+  }
+}
+```
+
+### Source Data
+
+```json
+{
+  "quantity": "abc"  // ❌ Cannot parse as integer
+}
+```
+
+### Transformation Result
+
+```typescript
+parseInt("abc") = NaN  // ❌ Not a number
+```
+
+### Error Result
+```typescript
+GraphQLExecutionError {
+  name: "GraphQLExecutionError",
+  message: "Expected type Int!, found NaN",
+  graphqlErrors: [
+    {
+      message: "Expected type Int!, found NaN",
+      path: ["createInventoryPosition", "input", "quantity"],
+      extensions: { "code": "BAD_USER_INPUT" }
+    }
+  ]
+}
+```
+
+### Impact
+
+✅ Fluent **REJECTS** mutation - No data created
+
+### How to Fix
+
+**Option 1: Validate and provide default**
+```json
+{
+  "quantity": {
+    "source": "quantity",
+    "resolver": "sdk.parseInt",
+    "defaultValue": 0  // ✅ Fallback for NaN
+  }
+}
+```
+
+**Option 2: Custom resolver with validation**
+```typescript
+const customResolvers = {
+  'custom.parseIntSafe': (value: any) => {
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+      throw new Error(`Cannot parse '${value}' as integer`);
+    }
+    return parsed;
+  }
+};
+```
+
+## Scenario 5: Array Validation Failure
+
+### The Problem
+
+Array doesn't meet validation constraints (minItems, maxItems).
+
+### Mapping Configuration
+
+```json
+{
+  "items": {
+    "_array": true,
+    "_validation": {
+      "minItems": 1,
+      "maxItems": 100
+    },
+    "source": "product-lineitems.product-lineitem"
+  }
+}
+```
+
+### Source Data - Empty Array
+
+```json
+{
+  "product-lineitems": {
+    "product-lineitem": []  // ❌ Empty array, minItems is 1
+  }
+}
+```
+
+### Error Result
+
+```typescript
+MappingError: Array must have at least 1 items, got 0
+  field: "items"
+  sourcePath: "product-lineitems.product-lineitem"
+```
+
+### Impact
+
+✅ Mutation **NEVER EXECUTED** - No data created
+
+### How to Fix
+
+**Option 1: Ensure source has items**
+```json
+{
+  "product-lineitems": {
+    "product-lineitem": [
+      { "ref": "ITEM-001" }  // ✅ At least one item
+    ]
+  }
+}
+```
+
+**Option 2: Adjust validation**
+```json
+{
+  "items": {
+    "_array": true,
+    "_validation": {
+      "minItems": 0  // ✅ Allow empty arrays
+    },
+    "source": "product-lineitems.product-lineitem"
+  }
+}
+```
+
+## Scenario 6: Invalid XML
+
+### The Problem
+
+Source file is malformed and cannot be parsed.
+
+### Input XML
+
+```xml
+<order>
+  <customer-email>test@example.com
+  <!-- ❌ Missing closing tag for customer-email and order -->
+```
+
+### Error Result
+
+```typescript
+FileParsingError: Failed to parse XML: Unclosed tag 'customer-email'
+  fileName: "order.xml"
+  lineNumber: 2
+  code: "PARSE_ERROR"
+  context: {
+    originalError: SyntaxError("Unclosed tag 'customer-email'")
+  }
+```
+
+### Impact
+
+✅ Mutation **NEVER ATTEMPTED** - No data created (parsing failed before mapping)
+
+### How to Fix
+
+Fix the XML syntax:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<order>
+  <customer-email>test@example.com</customer-email>  <!-- ✅ Properly closed -->
+</order>
+```
+
+## Scenario 7: Invalid JSON
+
+### The Problem
+
+JSON syntax is invalid.
+
+### Input JSON
+
+```json
+{
+  "order": {
+    "ref": "ORDER-123",
+    "status": active  // ❌ Unquoted string value
+  }
+}
+```
+
+### Error Result
+
+```typescript
+FileParsingError: Failed to parse JSON: Unexpected token a in JSON at position 45
+  fileName: "order.json"
+  code: "PARSE_ERROR"
+  context: {
+    originalError: SyntaxError("Unexpected token a...")
+  }
+```
+
+### Impact
+
+✅ Mutation **NEVER ATTEMPTED** - No data created
+
+### How to Fix
+
+Quote string values:
+
+```json
+{
+  "order": {
+    "ref": "ORDER-123",
+    "status": "active"  // ✅ Quoted string
+  }
+}
+```
+
+## Scenario 8: UTF-8 Encoding Issue
+
+### The Problem
+
+File contains invalid UTF-8 sequences or special characters that aren't handled.
+
+### Input (Binary representation)
+
+```
+0xFF 0xFE <order>...  // ❌ BOM (Byte Order Mark) at start
+```
+
+### What Happens
+
+The SDK automatically handles UTF-8 BOMs:
+
+```typescript
+// XMLParserService preprocessing
+private preprocessXML(xmlContent: string): string {
+  // Remove BOM (Byte Order Mark) if present
+  let cleaned = xmlContent.replace(/^\uFEFF/, '');  // ✅ BOM removed
+  return cleaned;
+}
+```
+
+### Result
+
+✅ **No error** - BOM is automatically removed and parsing succeeds
+
+### Supported Characters
+
+All UTF-8 characters are supported:
+
+```xml
+<order>
+  <customer>
+    <name>José García</name>
+    <email>josé@example.com</email>
+    <notes>Special chars: &amp; &lt; &gt; &quot; &apos; 中文 🎉</notes>
+  </customer>
+</order>
+```
+
+✅ **Result:** Parses correctly, all characters preserved
+
+## Scenario 9: Network Timeout
+### The Problem
+API request times out or network connection fails.
+
+### Error Result
+```typescript
+// FluentClient throws FluentAPIError for 5xx, or standard Error for network
+Error: network timeout at: https://api.fluentcommerce.com/graphql
+// OR
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 503",
+  statusCode: 503,
+  details: "Service Unavailable"
+}
+```
+
+### Impact
+❓ **Unknown** - Mutation may or may not have been created (network failure)
+
+### How to Handle
+Retry with exponential backoff. The SDK's `FluentClient` automatically retries 5xx errors and 401s. For network timeouts (which throw standard `Error`), you should implement retry logic:
+
+```typescript
+import { FluentAPIError } from '@fluentcommerce/fc-connect-sdk';
+
+async function executeWithRetry(operation: () => Promise<any>, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      // Retry 5xx or network errors
+      const isRetryable = (error instanceof FluentAPIError && error.statusCode >= 500) ||
+                          error.message.includes('network') ||
+                          error.message.includes('timeout');
+
+      if (isRetryable && attempt < maxRetries) {
+        const delay = Math.pow(2, attempt) * 1000;
+        console.log(`Transient error - retrying in ${delay}ms...`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+```
+
+## Scenario 10: Rate Limit Exceeded
+
+### The Problem
+Too many API requests in short time period (HTTP 429).
+
+### Error Result
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 429",
+  statusCode: 429,
+  details: "Too Many Requests"
+}
+```
+
+### Impact
+✅ Mutation **NOT EXECUTED** - Rate limit hit before processing
+
+### How to Handle
+Check `statusCode === 429` and retry with backoff:
+
+```typescript
+import { FluentAPIError } from '@fluentcommerce/fc-connect-sdk';
+
+async function handleRateLimit(operation: () => Promise<any>) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof FluentAPIError && error.statusCode === 429) {
+      console.log('Rate limit hit - waiting 60s...');
+      await new Promise(resolve => setTimeout(resolve, 60000));
+      return handleRateLimit(operation); // Retry
+    }
+    throw error;
+  }
+}
+```
+
+## Summary Table
+
+| Scenario | Error Class | Mutation Sent? | Data Created? | Retryable? |
+|----------|-------------|----------------|---------------|------------|
+| Wrong source path | `PathResolutionError` | ❌ No | ❌ No | ❌ No |
+| Missing required field | `MappingError` | ❌ No | ❌ No | ❌ No |
+| Wrong GraphQL field | `GraphQLExecutionError` | ✅ Yes | ❌ No | ❌ No |
+| Type mismatch | `GraphQLExecutionError` | ✅ Yes | ❌ No | ❌ No |
+| Array validation | `MappingError` | ❌ No | ❌ No | ❌ No |
+| Invalid XML | `FileParsingError` | ❌ No | ❌ No | ❌ No |
+| Invalid JSON | `FileParsingError` | ❌ No | ❌ No | ❌ No |
+| UTF-8 BOM | None (handled) | ✅ Yes | ✅ Yes | N/A |
+| Network timeout | `FluentAPIError` (5xx) or Error | ❓ Maybe | ❓ Maybe | ✅ Yes |
+| Rate limit | `FluentAPIError` (429) | ❌ No | ❌ No | ✅ Yes |
+
+## Key Takeaways
+
+- 🎯 **Parsing errors** prevent mutations from being sent (fail-fast)
+- 🎯 **Mapping errors** prevent mutations from being sent (fail-fast)
+- 🎯 **GraphQL errors** mean mutation was sent but rejected by Fluent
+- 🎯 **Network errors** are retryable - implement exponential backoff
+- 🎯 **Rate limits** are retryable - respect `retryAfter` value
+- 🎯 **UTF-8 handling** is automatic - BOM removal, special character support
+
+## Practice Exercise
+
+For each scenario, determine:
+1. Is the error retryable?
+2. Was the mutation sent to Fluent?
+3. What's the correct fix?
+
+**Scenarios:**
+1. XML file missing closing tag
+2. Network timeout during API call
+3. Required field is empty string
+4. Rate limit exceeded
+
+<details>
+<summary>Click to see answers</summary>
+
+1. **XML parsing error**
+   - Retryable? ❌ No
+   - Mutation sent? ❌ No
+   - Fix: Correct XML syntax
+
+2. **Network timeout**
+   - Retryable? ✅ Yes
+   - Mutation sent? ❓ Maybe (unknown state)
+   - Fix: Retry with exponential backoff
+
+3. **Empty required field**
+   - Retryable? ❌ No
+   - Mutation sent? ❌ No
+   - Fix: Provide value or make optional
+
+4. **Rate limit**
+   - Retryable? ✅ Yes
+   - Mutation sent? ❌ No
+   - Fix: Wait `retryAfter` seconds and retry
+
+</details>
+
+## Next Steps
+
+Continue to [Module 5: Calling Patterns →](./error-handling-05-calling-patterns.md) to learn code patterns for handling these errors effectively.
+
+---
+
+**Previous:** [← Module 3: UTF-8 Handling](./error-handling-03-utf8-handling.md)
+**Next:** [Module 5: Calling Patterns →](./error-handling-05-calling-patterns.md)