@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/error-handling-guide.md

@@ -1,936 +1,936 @@
-# Error Handling Guide
-
-**Complete guide** for handling errors when using GraphQL, Event API, Batch API, and Job API with proper try-catch patterns and response structures.
-
-## Table of Contents
-
-- [Quick Reference](#quick-reference)
-- [GraphQL Error Handling](#graphql-error-handling)
-- [Event API Error Handling](#event-api-error-handling)
-- [Batch API Error Handling](#batch-api-error-handling)
-- [Job API Error Handling](#job-api-error-handling)
-- [Error Types Reference](#error-types-reference)
-- [Best Practices](#best-practices)
-
----
-
-## Quick Reference
-
-### Error Types by API
-
-| API | Success Returns | Errors Throw |
-|-----|----------------|--------------|
-| **GraphQL** | `GraphQLResponse<T>` with `data` | `GraphQLExecutionError` or `FluentAPIError` |
-| **Event API** | `EventResponse` | `FluentAPIError` or `AuthenticationError` |
-| **Batch API** | `FluentBatchResponse` | `FluentAPIError` or `AuthenticationError` |
-| **Job API** | `FluentJobResponse` | `FluentAPIError` or `AuthenticationError` |
-
-### Common Error Classes
-
-```typescript
-import {
-  FluentAPIError,        // HTTP errors (400, 404, 422, 500, etc.)
-  AuthenticationError,   // 401 Unauthorized
-  GraphQLExecutionError  // GraphQL response errors
-} from '@fluentcommerce/fc-connect-sdk';
-```
-
----
-
-## GraphQL Error Handling
-
-### Success Response Structure
-
-```typescript
-interface GraphQLResponse<T> {
-  data?: T;                    // Query/mutation result data
-  errors?: Array<{             // Only present if errors occurred
-    message: string;
-    locations?: Array<{ line: number; column: number }>;
-    path?: (string | number)[];
-    extensions?: Record<string, any>;
-  }>;
-  extensions?: Record<string, unknown>;
-}
-```
-
-### Example: Successful GraphQL Query
-
-**Input:**
-```typescript
-const query = `
-  query GetProducts($first: Int!) {
-    products(first: $first) {
-      edges {
-        node {
-          id
-          ref
-          name
-        }
-      }
-    }
-  }
-`;
-
-const result = await client.graphql({
-  query,
-  variables: { first: 10 }
-});
-```
-
-**Success Output:**
-```typescript
-{
-  data: {
-    products: {
-      edges: [
-        {
-          node: {
-            id: "prod-123",
-            ref: "SKU-001",
-            name: "Product Name"
-          }
-        }
-      ]
-    }
-  }
-}
-```
-
-### Example: GraphQL Execution Error (Thrown)
-
-**Input:**
-```typescript
-const mutation = `
-  mutation CreateOrder($input: CreateOrderInput!) {
-    createOrder(input: $input) {
-      order {
-        id
-        ref
-      }
-    }
-  }
-`;
-
-try {
-  const result = await client.graphql({
-    query: mutation,
-    variables: {
-      input: {
-        ref: "DUPLICATE-REF-123"  // ← Order with this ref already exists
-      }
-    }
-  });
-} catch (error) {
-  // Error is THROWN, not returned in response
-}
-```
-
-**Error Thrown:**
-```typescript
-GraphQLExecutionError {
-  name: "GraphQLExecutionError",
-  message: "Order with reference DUPLICATE-REF-123 already exists",
-  graphqlErrors: [
-    {
-      message: "Order with reference DUPLICATE-REF-123 already exists",
-      path: ["createOrder"],
-      extensions: {
-        code: "C0121E",  // Client error code
-        field: "ref"
-      }
-    }
-  ],
-  query: "mutation CreateOrder...",
-  variables: { input: { ref: "DUPLICATE-REF-123" } }
-}
-```
-
-### Complete Try-Catch Pattern for GraphQL
-
-```typescript
-import { createClient, GraphQLExecutionError, FluentAPIError } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config });
-
-try {
-  const result = await client.graphql({
-    query: `
-      mutation UpdateInventory($input: UpdateInventoryInput!) {
-        updateInventory(input: $input) {
-          inventory {
-            id
-            quantity
-          }
-        }
-      }
-    `,
-    variables: {
-      input: {
-        locationRef: "LOC-001",
-        skuRef: "SKU-001",
-        quantity: 100
-      }
-    }
-  });
-
-  // ✅ SUCCESS: Use result.data
-  console.log('Inventory updated:', result.data?.updateInventory?.inventory);
-
-} catch (error) {
-  // GraphQL execution errors (validation, business logic, etc.)
-  if (error instanceof GraphQLExecutionError) {
-    console.error('GraphQL Error:', {
-      message: error.message,
-      errors: error.graphqlErrors,
-      errorCount: error.graphqlErrors.length,
-      isValidationError: error.isValidationError(),  // Helper method
-      isAuthError: error.isAuthError()                // Helper method
-    });
-
-    // Check specific error codes
-    const firstError = error.graphqlErrors[0];
-    if (firstError.extensions?.code === 'C0121E') {
-      console.error('Duplicate entity - order already exists');
-    }
-
-  // HTTP errors (400, 401, 404, 500, etc.)
-  } else if (error instanceof FluentAPIError) {
-    console.error('HTTP Error:', {
-      statusCode: error.statusCode,
-      message: error.message,
-      details: error.details
-    });
-
-  // Other errors (network, timeout, etc.)
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
-### GraphQL Error Response Examples
-
-**Example 1: Validation Error**
-```typescript
-GraphQLExecutionError {
-  message: "GraphQL execution failed",
-  graphqlErrors: [
-    {
-      message: "Variable '$input' got invalid value { quantity: -10 }",
-      locations: [{ line: 2, column: 25 }],
-      extensions: {
-        code: "BAD_USER_INPUT",
-        field: "quantity"
-      }
-    }
-  ]
-}
-```
-
-**Example 2: Entity Not Found**
-```typescript
-GraphQLExecutionError {
-  message: "Location not found",
-  graphqlErrors: [
-    {
-      message: "Location with reference LOC-999 not found",
-      path: ["updateInventory"],
-      extensions: {
-        code: "C0120E",
-        entityType: "LOCATION"
-      }
-    }
-  ]
-}
-```
-
-**Example 3: Authentication Error**
-```typescript
-GraphQLExecutionError {
-  message: "Unauthorized",
-  graphqlErrors: [
-    {
-      message: "You must be authenticated to perform this action",
-      extensions: {
-        code: "UNAUTHENTICATED"
-      }
-    }
-  ]
-}
-```
-
----
-
-## Event API Error Handling
-
-### Success Response Structure
-
-```typescript
-interface EventResponse {
-  success: boolean;        // Always true for successful responses
-  id?: string;            // Event ID (if returned by API)
-  status?: string;        // Event status (CREATED, COMPLETED, etc.)
-  statusCode: number;     // HTTP status code (200, 201, 202) - Consistent with error.statusCode
-  message?: string;       // Optional message from API
-}
-```
-
-### Example: Successful Event
-
-**Input:**
-```typescript
-const event = {
-  retailerId: "2",
-  name: "OrderCancel1",
-  entityRef: "ORDER-123",
-  entityType: "ORDER"
-};
-
-const result = await client.sendEvent(event, 'async');
-```
-
-**Success Output:**
-```typescript
-{
-  success: true,
-  statusCode: 200
-}
-```
-
-### Example: Event Error (Thrown)
-
-**Input:**
-```typescript
-try {
-  await client.sendEvent({
-    retailerId: "2",
-    name: "InvalidEventName",  // ← No workflow matches this event
-    entityRef: "ORDER-123",
-    entityType: "ORDER"
-  }, 'sync');
-} catch (error) {
-  // Error is THROWN
-}
-```
-
-**Error Thrown:**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 404",
-  statusCode: 404,
-  details: "No workflow rule matched this event"
-}
-```
-
-### Complete Try-Catch Pattern for Event API
-
-```typescript
-import { createClient, FluentAPIError, AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config });
-
-try {
-  const result = await client.sendEvent({
-    retailerId: "2",
-    name: "PRODUCT.UPDATE",
-    entityRef: "SKU-001",
-    entityType: "PRODUCT",
-    attributes: {
-      quantity: 100,
-      price: 29.99
-    }
-  }, 'async');  // 'sync' or 'async'
-
-  // ✅ SUCCESS: Check result.success
-  console.log('Event sent:', {
-    success: result.success,
-    statusCode: result.statusCode,
-    eventId: result.id
-  });
-
-} catch (error) {
-  // Authentication errors (401)
-  if (error instanceof AuthenticationError) {
-    console.error('Authentication failed:', {
-      statusCode: error.statusCode,  // Always 401
-      message: error.message,
-      code: error.code,               // "AUTHENTICATION_ERROR"
-      details: error.details
-    });
-    // Check credentials, refresh token
-
-  // Other HTTP errors (400, 404, 422, 500, etc.)
-  } else if (error instanceof FluentAPIError) {
-    console.error('Event API Error:', {
-      statusCode: error.statusCode,
-      message: error.message,
-      details: error.details
-    });
-
-    // Handle specific status codes
-    if (error.statusCode === 404) {
-      console.error('No workflow matched this event');
-    } else if (error.statusCode === 400) {
-      console.error('Invalid event payload');
-    } else if (error.statusCode === 422) {
-      console.error('Event validation failed');
-    }
-
-  // Other errors
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
-### Event API Error Examples
-
-**Example 1: Missing retailerId (SDK Validation)**
-```typescript
-// SDK catches this BEFORE API call
-FluentValidationError {
-  name: "FluentValidationError",
-  message: "retailerId is required for Event API",
-  code: "VALIDATION_ERROR",
-  statusCode: 400
-}
-```
-
-**Example 2: No Workflow Match (404)**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 404",
-  statusCode: 404,
-  details: "No workflow rule matched this event"
-}
-```
-
-**Example 3: Invalid Event Name (400)**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 400",
-  statusCode: 400,
-  details: "Bad Request - Invalid event configuration"
-}
-```
-
----
-
-## Batch API Error Handling
-
-### Success Response Structure
-
-```typescript
-interface FluentBatchResponse {
-  id: string;                    // Batch ID
-  jobId: string;                 // Job ID
-  status: FluentBatchStatus;     // PENDING | PROCESSING | COMPLETED | FAILED
-  processed: number;             // Records processed
-  succeeded: number;              // Records succeeded
-  failed: number;                // Records failed
-  errors?: Array<{               // Failed record details
-    recordIndex: number;
-    error: string;
-    ref?: string;
-  }>;
-  createdAt?: string;
-  updatedAt?: string;
-}
-```
-
-### Example: Successful Batch
-
-**Input:**
-```typescript
-const batch = {
-  jobId: "job-123",
-  records: [
-    {
-      locationRef: "LOC-001",
-      skuRef: "SKU-001",
-      quantity: 100
-    },
-    {
-      locationRef: "LOC-001",
-      skuRef: "SKU-002",
-      quantity: 50
-    }
-  ]
-};
-
-const result = await client.createBatch(batch);
-```
-
-**Success Output:**
-```typescript
-{
-  id: "batch-456",
-  jobId: "job-123",
-  status: "PENDING",
-  processed: 2,
-  succeeded: 2,
-  failed: 0
-}
-```
-
-### Example: Partial Batch Failure
-
-**Input:**
-```typescript
-const batch = {
-  jobId: "job-123",
-  records: [
-    {
-      locationRef: "LOC-001",
-      skuRef: "SKU-001",
-      quantity: 100  // ✅ Valid
-    },
-    {
-      locationRef: "INVALID-LOC",  // ❌ Invalid location
-      skuRef: "SKU-002",
-      quantity: 50
-    }
-  ]
-};
-
-const result = await client.createBatch(batch);
-```
-
-**Success Output (with errors):**
-```typescript
-{
-  id: "batch-456",
-  jobId: "job-123",
-  status: "COMPLETED",
-  processed: 2,
-  succeeded: 1,
-  failed: 1,
-  errors: [
-    {
-      recordIndex: 1,
-      error: "Location with reference INVALID-LOC not found",
-      ref: "SKU-002"
-    }
-  ]
-}
-```
-
-### Complete Try-Catch Pattern for Batch API
-
-```typescript
-import { createClient, FluentAPIError, AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config });
-
-try {
-  const result = await client.createBatch({
-    jobId: "job-123",
-    records: [
-      { locationRef: "LOC-001", skuRef: "SKU-001", quantity: 100 },
-      { locationRef: "LOC-001", skuRef: "SKU-002", quantity: 50 }
-    ]
-  });
-
-  // ✅ SUCCESS: Check result.status and result.failed
-  console.log('Batch created:', {
-    batchId: result.id,
-    status: result.status,
-    processed: result.processed,
-    succeeded: result.succeeded,
-    failed: result.failed
-  });
-
-  // Check for partial failures
-  if (result.failed > 0) {
-    console.warn('Some records failed:', {
-      failedCount: result.failed,
-      errors: result.errors
-    });
-
-    // Process failed records
-    result.errors?.forEach(error => {
-      console.error(`Record ${error.recordIndex} failed:`, error.error);
-    });
-  }
-
-} catch (error) {
-  // Authentication errors (401)
-  if (error instanceof AuthenticationError) {
-    console.error('Authentication failed:', {
-      statusCode: error.statusCode,
-      message: error.message
-    });
-
-  // HTTP errors (400, 404, 422, 500, etc.)
-  } else if (error instanceof FluentAPIError) {
-    console.error('Batch API Error:', {
-      statusCode: error.statusCode,
-      message: error.message,
-      details: error.details
-    });
-
-    // Handle specific status codes
-    if (error.statusCode === 400) {
-      console.error('Invalid batch payload');
-    } else if (error.statusCode === 404) {
-      console.error('Job not found');
-    }
-
-  // Other errors
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
-### Batch API Error Examples
-
-**Example 1: Invalid Job ID (404)**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 404",
-  statusCode: 404,
-  details: "Job with ID job-999 not found"
-}
-```
-
-**Example 2: Invalid Batch Payload (400)**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 400",
-  statusCode: 400,
-  details: "Invalid batch payload: missing required field 'records'"
-}
-```
-
----
-
-## Job API Error Handling
-
-### Success Response Structure
-
-```typescript
-interface FluentJobResponse {
-  id: string;                    // Job ID
-  name: string;                  // Job name
-  status: FluentJobStatus;       // CREATED | PROCESSING | COMPLETED | FAILED | PARTIAL
-  retailerId: string;
-  metadata?: Record<string, any>;
-  createdAt?: string;
-  updatedAt?: string;
-}
-```
-
-### Example: Successful Job Creation
-
-**Input:**
-```typescript
-const job = {
-  name: "Inventory Sync",
-  retailerId: "2",
-  metadata: {
-    source: "SFTP",
-    filename: "inventory-2025-01-22.csv"
-  }
-};
-
-const result = await client.createJob(job);
-```
-
-**Success Output:**
-```typescript
-{
-  id: "job-123",
-  name: "Inventory Sync",
-  status: "CREATED",
-  retailerId: "2",
-  metadata: {
-    source: "SFTP",
-    filename: "inventory-2025-01-22.csv"
-  },
-  createdAt: "2025-01-22T10:30:00Z"
-}
-```
-
-### Example: Job Status Check
-
-**Input:**
-```typescript
-const status = await client.getJobStatus("job-123");
-```
-
-**Success Output:**
-```typescript
-{
-  id: "job-123",
-  name: "Inventory Sync",
-  status: "COMPLETED",
-  retailerId: "2",
-  updatedAt: "2025-01-22T10:35:00Z"
-}
-```
-
-### Complete Try-Catch Pattern for Job API
-
-```typescript
-import { createClient, FluentAPIError, AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config });
-
-try {
-  // Create job
-  const job = await client.createJob({
-    name: "Inventory Sync",
-    retailerId: "2",
-    metadata: {
-      source: "SFTP",
-      filename: "inventory.csv"
-    }
-  });
-
-  console.log('Job created:', {
-    jobId: job.id,
-    status: job.status
-  });
-
-  // Get job status
-  const status = await client.getJobStatus(job.id);
-  console.log('Job status:', {
-    status: status.status,
-    updatedAt: status.updatedAt
-  });
-
-  // Get job results
-  const results = await client.getJobResults(job.id);
-  console.log('Job results:', {
-    processed: results.results?.processed,
-    success: results.results?.success,
-    failed: results.results?.failed
-  });
-
-} catch (error) {
-  // Authentication errors (401)
-  if (error instanceof AuthenticationError) {
-    console.error('Authentication failed:', {
-      statusCode: error.statusCode,
-      message: error.message
-    });
-
-  // HTTP errors (400, 404, 422, 500, etc.)
-  } else if (error instanceof FluentAPIError) {
-    console.error('Job API Error:', {
-      statusCode: error.statusCode,
-      message: error.message,
-      details: error.details
-    });
-
-    // Handle specific status codes
-    if (error.statusCode === 404) {
-      console.error('Job not found');
-    } else if (error.statusCode === 400) {
-      console.error('Invalid job payload');
-    }
-
-  // Other errors
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
-### Job API Error Examples
-
-**Example 1: Job Not Found (404)**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 404",
-  statusCode: 404,
-  details: "Job with ID job-999 not found"
-}
-```
-
-**Example 2: Missing retailerId (400)**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 400",
-  statusCode: 400,
-  details: "retailerId is required"
-}
-```
-
----
-
-## Error Types Reference
-
-### FluentAPIError
-
-HTTP errors from Fluent Commerce API:
-
-```typescript
-class FluentAPIError extends Error {
-  name: "FluentAPIError";
-  message: string;              // Error description
-  statusCode: number;           // HTTP status (400, 404, 422, 500, etc.)
-  details?: any;                // Additional error context
-  errors?: Array<any>;          // Validation errors (if applicable)
-}
-```
-
-**Common Status Codes:**
-- `400` - Bad Request (invalid payload)
-- `401` - Unauthorized (use `AuthenticationError` instead)
-- `403` - Forbidden (insufficient permissions)
-- `404` - Not Found (entity doesn't exist)
-- `422` - Unprocessable Entity (validation failed)
-- `429` - Too Many Requests (rate limited)
-- `500` - Internal Server Error (retry with backoff)
-
-### AuthenticationError
-
-OAuth2 authentication failures (401 Unauthorized):
-
-```typescript
-class AuthenticationError extends FluentAPIError {
-  name: "AuthenticationError";
-  statusCode: 401;             // Always 401
-  code: "AUTHENTICATION_ERROR";
-  details?: {
-    response?: string;          // API response body
-  };
-}
-```
-
-**When Thrown:**
-- Token expired or invalid
-- Credentials incorrect
-- Token refresh failed after retries
-
-### GraphQLExecutionError
-
-GraphQL query/mutation execution errors:
-
-```typescript
-class GraphQLExecutionError extends Error {
-  name: "GraphQLExecutionError";
-  message: string;
-  graphqlErrors: Array<{
-    message: string;
-    locations?: Array<{ line: number; column: number }>;
-    path?: (string | number)[];
-    extensions?: Record<string, any>;
-  }>;
-  query?: string;               // Original query
-  variables?: Record<string, any>; // Original variables
-
-  // Helper methods
-  getErrorMessages(): string[];
-  isValidationError(): boolean;
-  isAuthError(): boolean;
-}
-```
-
-**When Thrown:**
-- GraphQL validation errors
-- Business logic errors (duplicate ref, entity not found)
-- Authentication/authorization failures
-- Schema mismatches
-
----
-
-## Best Practices
-
-### 1. Always Use Try-Catch
-
-```typescript
-// ✅ GOOD
-try {
-  const result = await client.graphql({ query });
-  // Handle success
-} catch (error) {
-  // Handle error
-}
-
-// ❌ BAD - No error handling
-const result = await client.graphql({ query });
-```
-
-### 2. Check Error Types
-
-```typescript
-// ✅ GOOD - Specific error handling
-catch (error) {
-  if (error instanceof GraphQLExecutionError) {
-    // Handle GraphQL errors
-  } else if (error instanceof AuthenticationError) {
-    // Handle auth errors
-  } else if (error instanceof FluentAPIError) {
-    // Handle HTTP errors
-  }
-}
-
-// ❌ BAD - Generic error handling
-catch (error) {
-  console.error('Error:', error);  // Not helpful
-}
-```
-
-### 3. Handle Partial Failures
-
-```typescript
-// ✅ GOOD - Check for partial failures
-const batch = await client.createBatch({ jobId, records });
-
-if (batch.failed > 0) {
-  console.warn(`${batch.failed} records failed`);
-  batch.errors?.forEach(error => {
-    // Log or retry failed records
-  });
-}
-```
-
-### 4. Log Error Context
-
-```typescript
-// ✅ GOOD - Log with context
-catch (error) {
-  if (error instanceof GraphQLExecutionError) {
-    log.error('GraphQL error', {
-      errors: error.graphqlErrors,
-      query: error.query?.substring(0, 100),
-      variables: error.variables
-    });
-  }
-}
-```
-
-### 5. Retry Transient Errors
-
-```typescript
-// ✅ GOOD - Retry transient errors
-catch (error) {
-  if (error instanceof FluentAPIError) {
-    // Retry on 5xx errors
-    if (error.statusCode >= 500) {
-      // Retry with exponential backoff
-    }
-    // Don't retry on 4xx errors (except 401)
-  }
-}
-```
-
----
-
-## Related Documentation
-
-- [API Reference - Error Handling](../02-CORE-GUIDES/api-reference/modules/api-reference-11-error-handling.md)
-- [Error Handling Patterns](../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md)
-- [GraphQL Error Classification](../02-CORE-GUIDES/api-reference/graphql-error-classification.md)
-
+# Error Handling Guide
+
+**Complete guide** for handling errors when using GraphQL, Event API, Batch API, and Job API with proper try-catch patterns and response structures.
+
+## Table of Contents
+
+- [Quick Reference](#quick-reference)
+- [GraphQL Error Handling](#graphql-error-handling)
+- [Event API Error Handling](#event-api-error-handling)
+- [Batch API Error Handling](#batch-api-error-handling)
+- [Job API Error Handling](#job-api-error-handling)
+- [Error Types Reference](#error-types-reference)
+- [Best Practices](#best-practices)
+
+---
+
+## Quick Reference
+
+### Error Types by API
+
+| API | Success Returns | Errors Throw |
+|-----|----------------|--------------|
+| **GraphQL** | `GraphQLResponse<T>` with `data` | `GraphQLExecutionError` or `FluentAPIError` |
+| **Event API** | `EventResponse` | `FluentAPIError` or `AuthenticationError` |
+| **Batch API** | `FluentBatchResponse` | `FluentAPIError` or `AuthenticationError` |
+| **Job API** | `FluentJobResponse` | `FluentAPIError` or `AuthenticationError` |
+
+### Common Error Classes
+
+```typescript
+import {
+  FluentAPIError,        // HTTP errors (400, 404, 422, 500, etc.)
+  AuthenticationError,   // 401 Unauthorized
+  GraphQLExecutionError  // GraphQL response errors
+} from '@fluentcommerce/fc-connect-sdk';
+```
+
+---
+
+## GraphQL Error Handling
+
+### Success Response Structure
+
+```typescript
+interface GraphQLResponse<T> {
+  data?: T;                    // Query/mutation result data
+  errors?: Array<{             // Only present if errors occurred
+    message: string;
+    locations?: Array<{ line: number; column: number }>;
+    path?: (string | number)[];
+    extensions?: Record<string, any>;
+  }>;
+  extensions?: Record<string, unknown>;
+}
+```
+
+### Example: Successful GraphQL Query
+
+**Input:**
+```typescript
+const query = `
+  query GetProducts($first: Int!) {
+    products(first: $first) {
+      edges {
+        node {
+          id
+          ref
+          name
+        }
+      }
+    }
+  }
+`;
+
+const result = await client.graphql({
+  query,
+  variables: { first: 10 }
+});
+```
+
+**Success Output:**
+```typescript
+{
+  data: {
+    products: {
+      edges: [
+        {
+          node: {
+            id: "prod-123",
+            ref: "SKU-001",
+            name: "Product Name"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+### Example: GraphQL Execution Error (Thrown)
+
+**Input:**
+```typescript
+const mutation = `
+  mutation CreateOrder($input: CreateOrderInput!) {
+    createOrder(input: $input) {
+      order {
+        id
+        ref
+      }
+    }
+  }
+`;
+
+try {
+  const result = await client.graphql({
+    query: mutation,
+    variables: {
+      input: {
+        ref: "DUPLICATE-REF-123"  // ← Order with this ref already exists
+      }
+    }
+  });
+} catch (error) {
+  // Error is THROWN, not returned in response
+}
+```
+
+**Error Thrown:**
+```typescript
+GraphQLExecutionError {
+  name: "GraphQLExecutionError",
+  message: "Order with reference DUPLICATE-REF-123 already exists",
+  graphqlErrors: [
+    {
+      message: "Order with reference DUPLICATE-REF-123 already exists",
+      path: ["createOrder"],
+      extensions: {
+        code: "C0121E",  // Client error code
+        field: "ref"
+      }
+    }
+  ],
+  query: "mutation CreateOrder...",
+  variables: { input: { ref: "DUPLICATE-REF-123" } }
+}
+```
+
+### Complete Try-Catch Pattern for GraphQL
+
+```typescript
+import { createClient, GraphQLExecutionError, FluentAPIError } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config });
+
+try {
+  const result = await client.graphql({
+    query: `
+      mutation UpdateInventory($input: UpdateInventoryInput!) {
+        updateInventory(input: $input) {
+          inventory {
+            id
+            quantity
+          }
+        }
+      }
+    `,
+    variables: {
+      input: {
+        locationRef: "LOC-001",
+        skuRef: "SKU-001",
+        quantity: 100
+      }
+    }
+  });
+
+  // ✅ SUCCESS: Use result.data
+  console.log('Inventory updated:', result.data?.updateInventory?.inventory);
+
+} catch (error) {
+  // GraphQL execution errors (validation, business logic, etc.)
+  if (error instanceof GraphQLExecutionError) {
+    console.error('GraphQL Error:', {
+      message: error.message,
+      errors: error.graphqlErrors,
+      errorCount: error.graphqlErrors.length,
+      isValidationError: error.isValidationError(),  // Helper method
+      isAuthError: error.isAuthError()                // Helper method
+    });
+
+    // Check specific error codes
+    const firstError = error.graphqlErrors[0];
+    if (firstError.extensions?.code === 'C0121E') {
+      console.error('Duplicate entity - order already exists');
+    }
+
+  // HTTP errors (400, 401, 404, 500, etc.)
+  } else if (error instanceof FluentAPIError) {
+    console.error('HTTP Error:', {
+      statusCode: error.statusCode,
+      message: error.message,
+      details: error.details
+    });
+
+  // Other errors (network, timeout, etc.)
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### GraphQL Error Response Examples
+
+**Example 1: Validation Error**
+```typescript
+GraphQLExecutionError {
+  message: "GraphQL execution failed",
+  graphqlErrors: [
+    {
+      message: "Variable '$input' got invalid value { quantity: -10 }",
+      locations: [{ line: 2, column: 25 }],
+      extensions: {
+        code: "BAD_USER_INPUT",
+        field: "quantity"
+      }
+    }
+  ]
+}
+```
+
+**Example 2: Entity Not Found**
+```typescript
+GraphQLExecutionError {
+  message: "Location not found",
+  graphqlErrors: [
+    {
+      message: "Location with reference LOC-999 not found",
+      path: ["updateInventory"],
+      extensions: {
+        code: "C0120E",
+        entityType: "LOCATION"
+      }
+    }
+  ]
+}
+```
+
+**Example 3: Authentication Error**
+```typescript
+GraphQLExecutionError {
+  message: "Unauthorized",
+  graphqlErrors: [
+    {
+      message: "You must be authenticated to perform this action",
+      extensions: {
+        code: "UNAUTHENTICATED"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Event API Error Handling
+
+### Success Response Structure
+
+```typescript
+interface EventResponse {
+  success: boolean;        // Always true for successful responses
+  id?: string;            // Event ID (if returned by API)
+  status?: string;        // Event status (CREATED, COMPLETED, etc.)
+  statusCode: number;     // HTTP status code (200, 201, 202) - Consistent with error.statusCode
+  message?: string;       // Optional message from API
+}
+```
+
+### Example: Successful Event
+
+**Input:**
+```typescript
+const event = {
+  retailerId: "2",
+  name: "OrderCancel1",
+  entityRef: "ORDER-123",
+  entityType: "ORDER"
+};
+
+const result = await client.sendEvent(event, 'async');
+```
+
+**Success Output:**
+```typescript
+{
+  success: true,
+  statusCode: 200
+}
+```
+
+### Example: Event Error (Thrown)
+
+**Input:**
+```typescript
+try {
+  await client.sendEvent({
+    retailerId: "2",
+    name: "InvalidEventName",  // ← No workflow matches this event
+    entityRef: "ORDER-123",
+    entityType: "ORDER"
+  }, 'sync');
+} catch (error) {
+  // Error is THROWN
+}
+```
+
+**Error Thrown:**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 404",
+  statusCode: 404,
+  details: "No workflow rule matched this event"
+}
+```
+
+### Complete Try-Catch Pattern for Event API
+
+```typescript
+import { createClient, FluentAPIError, AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config });
+
+try {
+  const result = await client.sendEvent({
+    retailerId: "2",
+    name: "PRODUCT.UPDATE",
+    entityRef: "SKU-001",
+    entityType: "PRODUCT",
+    attributes: {
+      quantity: 100,
+      price: 29.99
+    }
+  }, 'async');  // 'sync' or 'async'
+
+  // ✅ SUCCESS: Check result.success
+  console.log('Event sent:', {
+    success: result.success,
+    statusCode: result.statusCode,
+    eventId: result.id
+  });
+
+} catch (error) {
+  // Authentication errors (401)
+  if (error instanceof AuthenticationError) {
+    console.error('Authentication failed:', {
+      statusCode: error.statusCode,  // Always 401
+      message: error.message,
+      code: error.code,               // "AUTHENTICATION_ERROR"
+      details: error.details
+    });
+    // Check credentials, refresh token
+
+  // Other HTTP errors (400, 404, 422, 500, etc.)
+  } else if (error instanceof FluentAPIError) {
+    console.error('Event API Error:', {
+      statusCode: error.statusCode,
+      message: error.message,
+      details: error.details
+    });
+
+    // Handle specific status codes
+    if (error.statusCode === 404) {
+      console.error('No workflow matched this event');
+    } else if (error.statusCode === 400) {
+      console.error('Invalid event payload');
+    } else if (error.statusCode === 422) {
+      console.error('Event validation failed');
+    }
+
+  // Other errors
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### Event API Error Examples
+
+**Example 1: Missing retailerId (SDK Validation)**
+```typescript
+// SDK catches this BEFORE API call
+FluentValidationError {
+  name: "FluentValidationError",
+  message: "retailerId is required for Event API",
+  code: "VALIDATION_ERROR",
+  statusCode: 400
+}
+```
+
+**Example 2: No Workflow Match (404)**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 404",
+  statusCode: 404,
+  details: "No workflow rule matched this event"
+}
+```
+
+**Example 3: Invalid Event Name (400)**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 400",
+  statusCode: 400,
+  details: "Bad Request - Invalid event configuration"
+}
+```
+
+---
+
+## Batch API Error Handling
+
+### Success Response Structure
+
+```typescript
+interface FluentBatchResponse {
+  id: string;                    // Batch ID
+  jobId: string;                 // Job ID
+  status: FluentBatchStatus;     // PENDING | PROCESSING | COMPLETED | FAILED
+  processed: number;             // Records processed
+  succeeded: number;              // Records succeeded
+  failed: number;                // Records failed
+  errors?: Array<{               // Failed record details
+    recordIndex: number;
+    error: string;
+    ref?: string;
+  }>;
+  createdAt?: string;
+  updatedAt?: string;
+}
+```
+
+### Example: Successful Batch
+
+**Input:**
+```typescript
+const batch = {
+  jobId: "job-123",
+  records: [
+    {
+      locationRef: "LOC-001",
+      skuRef: "SKU-001",
+      quantity: 100
+    },
+    {
+      locationRef: "LOC-001",
+      skuRef: "SKU-002",
+      quantity: 50
+    }
+  ]
+};
+
+const result = await client.createBatch(batch);
+```
+
+**Success Output:**
+```typescript
+{
+  id: "batch-456",
+  jobId: "job-123",
+  status: "PENDING",
+  processed: 2,
+  succeeded: 2,
+  failed: 0
+}
+```
+
+### Example: Partial Batch Failure
+
+**Input:**
+```typescript
+const batch = {
+  jobId: "job-123",
+  records: [
+    {
+      locationRef: "LOC-001",
+      skuRef: "SKU-001",
+      quantity: 100  // ✅ Valid
+    },
+    {
+      locationRef: "INVALID-LOC",  // ❌ Invalid location
+      skuRef: "SKU-002",
+      quantity: 50
+    }
+  ]
+};
+
+const result = await client.createBatch(batch);
+```
+
+**Success Output (with errors):**
+```typescript
+{
+  id: "batch-456",
+  jobId: "job-123",
+  status: "COMPLETED",
+  processed: 2,
+  succeeded: 1,
+  failed: 1,
+  errors: [
+    {
+      recordIndex: 1,
+      error: "Location with reference INVALID-LOC not found",
+      ref: "SKU-002"
+    }
+  ]
+}
+```
+
+### Complete Try-Catch Pattern for Batch API
+
+```typescript
+import { createClient, FluentAPIError, AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config });
+
+try {
+  const result = await client.createBatch({
+    jobId: "job-123",
+    records: [
+      { locationRef: "LOC-001", skuRef: "SKU-001", quantity: 100 },
+      { locationRef: "LOC-001", skuRef: "SKU-002", quantity: 50 }
+    ]
+  });
+
+  // ✅ SUCCESS: Check result.status and result.failed
+  console.log('Batch created:', {
+    batchId: result.id,
+    status: result.status,
+    processed: result.processed,
+    succeeded: result.succeeded,
+    failed: result.failed
+  });
+
+  // Check for partial failures
+  if (result.failed > 0) {
+    console.warn('Some records failed:', {
+      failedCount: result.failed,
+      errors: result.errors
+    });
+
+    // Process failed records
+    result.errors?.forEach(error => {
+      console.error(`Record ${error.recordIndex} failed:`, error.error);
+    });
+  }
+
+} catch (error) {
+  // Authentication errors (401)
+  if (error instanceof AuthenticationError) {
+    console.error('Authentication failed:', {
+      statusCode: error.statusCode,
+      message: error.message
+    });
+
+  // HTTP errors (400, 404, 422, 500, etc.)
+  } else if (error instanceof FluentAPIError) {
+    console.error('Batch API Error:', {
+      statusCode: error.statusCode,
+      message: error.message,
+      details: error.details
+    });
+
+    // Handle specific status codes
+    if (error.statusCode === 400) {
+      console.error('Invalid batch payload');
+    } else if (error.statusCode === 404) {
+      console.error('Job not found');
+    }
+
+  // Other errors
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### Batch API Error Examples
+
+**Example 1: Invalid Job ID (404)**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 404",
+  statusCode: 404,
+  details: "Job with ID job-999 not found"
+}
+```
+
+**Example 2: Invalid Batch Payload (400)**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 400",
+  statusCode: 400,
+  details: "Invalid batch payload: missing required field 'records'"
+}
+```
+
+---
+
+## Job API Error Handling
+
+### Success Response Structure
+
+```typescript
+interface FluentJobResponse {
+  id: string;                    // Job ID
+  name: string;                  // Job name
+  status: FluentJobStatus;       // CREATED | PROCESSING | COMPLETED | FAILED | PARTIAL
+  retailerId: string;
+  metadata?: Record<string, any>;
+  createdAt?: string;
+  updatedAt?: string;
+}
+```
+
+### Example: Successful Job Creation
+
+**Input:**
+```typescript
+const job = {
+  name: "Inventory Sync",
+  retailerId: "2",
+  metadata: {
+    source: "SFTP",
+    filename: "inventory-2025-01-22.csv"
+  }
+};
+
+const result = await client.createJob(job);
+```
+
+**Success Output:**
+```typescript
+{
+  id: "job-123",
+  name: "Inventory Sync",
+  status: "CREATED",
+  retailerId: "2",
+  metadata: {
+    source: "SFTP",
+    filename: "inventory-2025-01-22.csv"
+  },
+  createdAt: "2025-01-22T10:30:00Z"
+}
+```
+
+### Example: Job Status Check
+
+**Input:**
+```typescript
+const status = await client.getJobStatus("job-123");
+```
+
+**Success Output:**
+```typescript
+{
+  id: "job-123",
+  name: "Inventory Sync",
+  status: "COMPLETED",
+  retailerId: "2",
+  updatedAt: "2025-01-22T10:35:00Z"
+}
+```
+
+### Complete Try-Catch Pattern for Job API
+
+```typescript
+import { createClient, FluentAPIError, AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config });
+
+try {
+  // Create job
+  const job = await client.createJob({
+    name: "Inventory Sync",
+    retailerId: "2",
+    metadata: {
+      source: "SFTP",
+      filename: "inventory.csv"
+    }
+  });
+
+  console.log('Job created:', {
+    jobId: job.id,
+    status: job.status
+  });
+
+  // Get job status
+  const status = await client.getJobStatus(job.id);
+  console.log('Job status:', {
+    status: status.status,
+    updatedAt: status.updatedAt
+  });
+
+  // Get job results
+  const results = await client.getJobResults(job.id);
+  console.log('Job results:', {
+    processed: results.results?.processed,
+    success: results.results?.success,
+    failed: results.results?.failed
+  });
+
+} catch (error) {
+  // Authentication errors (401)
+  if (error instanceof AuthenticationError) {
+    console.error('Authentication failed:', {
+      statusCode: error.statusCode,
+      message: error.message
+    });
+
+  // HTTP errors (400, 404, 422, 500, etc.)
+  } else if (error instanceof FluentAPIError) {
+    console.error('Job API Error:', {
+      statusCode: error.statusCode,
+      message: error.message,
+      details: error.details
+    });
+
+    // Handle specific status codes
+    if (error.statusCode === 404) {
+      console.error('Job not found');
+    } else if (error.statusCode === 400) {
+      console.error('Invalid job payload');
+    }
+
+  // Other errors
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### Job API Error Examples
+
+**Example 1: Job Not Found (404)**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 404",
+  statusCode: 404,
+  details: "Job with ID job-999 not found"
+}
+```
+
+**Example 2: Missing retailerId (400)**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 400",
+  statusCode: 400,
+  details: "retailerId is required"
+}
+```
+
+---
+
+## Error Types Reference
+
+### FluentAPIError
+
+HTTP errors from Fluent Commerce API:
+
+```typescript
+class FluentAPIError extends Error {
+  name: "FluentAPIError";
+  message: string;              // Error description
+  statusCode: number;           // HTTP status (400, 404, 422, 500, etc.)
+  details?: any;                // Additional error context
+  errors?: Array<any>;          // Validation errors (if applicable)
+}
+```
+
+**Common Status Codes:**
+- `400` - Bad Request (invalid payload)
+- `401` - Unauthorized (use `AuthenticationError` instead)
+- `403` - Forbidden (insufficient permissions)
+- `404` - Not Found (entity doesn't exist)
+- `422` - Unprocessable Entity (validation failed)
+- `429` - Too Many Requests (rate limited)
+- `500` - Internal Server Error (retry with backoff)
+
+### AuthenticationError
+
+OAuth2 authentication failures (401 Unauthorized):
+
+```typescript
+class AuthenticationError extends FluentAPIError {
+  name: "AuthenticationError";
+  statusCode: 401;             // Always 401
+  code: "AUTHENTICATION_ERROR";
+  details?: {
+    response?: string;          // API response body
+  };
+}
+```
+
+**When Thrown:**
+- Token expired or invalid
+- Credentials incorrect
+- Token refresh failed after retries
+
+### GraphQLExecutionError
+
+GraphQL query/mutation execution errors:
+
+```typescript
+class GraphQLExecutionError extends Error {
+  name: "GraphQLExecutionError";
+  message: string;
+  graphqlErrors: Array<{
+    message: string;
+    locations?: Array<{ line: number; column: number }>;
+    path?: (string | number)[];
+    extensions?: Record<string, any>;
+  }>;
+  query?: string;               // Original query
+  variables?: Record<string, any>; // Original variables
+
+  // Helper methods
+  getErrorMessages(): string[];
+  isValidationError(): boolean;
+  isAuthError(): boolean;
+}
+```
+
+**When Thrown:**
+- GraphQL validation errors
+- Business logic errors (duplicate ref, entity not found)
+- Authentication/authorization failures
+- Schema mismatches
+
+---
+
+## Best Practices
+
+### 1. Always Use Try-Catch
+
+```typescript
+// ✅ GOOD
+try {
+  const result = await client.graphql({ query });
+  // Handle success
+} catch (error) {
+  // Handle error
+}
+
+// ❌ BAD - No error handling
+const result = await client.graphql({ query });
+```
+
+### 2. Check Error Types
+
+```typescript
+// ✅ GOOD - Specific error handling
+catch (error) {
+  if (error instanceof GraphQLExecutionError) {
+    // Handle GraphQL errors
+  } else if (error instanceof AuthenticationError) {
+    // Handle auth errors
+  } else if (error instanceof FluentAPIError) {
+    // Handle HTTP errors
+  }
+}
+
+// ❌ BAD - Generic error handling
+catch (error) {
+  console.error('Error:', error);  // Not helpful
+}
+```
+
+### 3. Handle Partial Failures
+
+```typescript
+// ✅ GOOD - Check for partial failures
+const batch = await client.createBatch({ jobId, records });
+
+if (batch.failed > 0) {
+  console.warn(`${batch.failed} records failed`);
+  batch.errors?.forEach(error => {
+    // Log or retry failed records
+  });
+}
+```
+
+### 4. Log Error Context
+
+```typescript
+// ✅ GOOD - Log with context
+catch (error) {
+  if (error instanceof GraphQLExecutionError) {
+    log.error('GraphQL error', {
+      errors: error.graphqlErrors,
+      query: error.query?.substring(0, 100),
+      variables: error.variables
+    });
+  }
+}
+```
+
+### 5. Retry Transient Errors
+
+```typescript
+// ✅ GOOD - Retry transient errors
+catch (error) {
+  if (error instanceof FluentAPIError) {
+    // Retry on 5xx errors
+    if (error.statusCode >= 500) {
+      // Retry with exponential backoff
+    }
+    // Don't retry on 4xx errors (except 401)
+  }
+}
+```
+
+---
+
+## Related Documentation
+
+- [API Reference - Error Handling](../02-CORE-GUIDES/api-reference/modules/api-reference-11-error-handling.md)
+- [Error Handling Patterns](../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md)
+- [GraphQL Error Classification](../02-CORE-GUIDES/api-reference/graphql-error-classification.md)
+