@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/03-PATTERN-GUIDES/error-handling/comprehensive-error-handling-guide.md

@@ -1,1437 +1,1437 @@
-# Comprehensive Error Handling Guide
-
-> **Complete guide** to error handling across GraphQL, Event API, Batch API, and Job API with live examples
-
-## Table of Contents
-
-1. [Error Types Overview](#error-types-overview)
-2. [Where is the Status Code?](#where-is-the-status-code)
-3. [Anatomy of an API Call](#anatomy-of-an-api-call)
-4. [Event API Error Handling](#event-api-error-handling)
-5. [GraphQL Error Handling](#graphql-error-handling)
-6. [Batch API Error Handling](#batch-api-error-handling)
-7. [Job API Error Handling](#job-api-error-handling)
-8. [Common Patterns](#common-patterns)
-9. [Live Examples](#live-examples)
-
----
-
-## Error Types Overview
-
-> **📚 For complete error type reference**, see [Module 2: Error Types & Codes](./modules/error-handling-02-error-types.md)
-
-**Quick Summary:**
-
-| Error Type | When Thrown | HTTP Status | Auto-Retry |
-|------------|-------------|-------------|------------|
-| **FluentAPIError** | HTTP errors (4xx, 5xx) | 400, 404, 500, etc. | ✅ Yes (401, 5xx) |
-| **AuthenticationError** | OAuth2 auth fails after 3 retries | 401 | N/A (already retried) |
-| **GraphQLExecutionError** | GraphQL returns errors in response | 200 (with errors) | ❌ No |
-
-### ⚡ How to Capture the Full Error Object
-
-Standard logging (like `JSON.stringify(error)`) often misses custom fields. Use this helper to capture the full structure for your logs:
-
-```typescript
-/**
- * Helper to extract full error details including HTTP status and response body
- */
-function extractError(error: any) {
-  // 1. Use toJSON() if available (e.g. GraphQLExecutionError, IngestionError)
-  if (typeof error.toJSON === 'function') {
-    return error.toJSON();
-  }
-
-  // 2. Manual extraction for FluentAPIError / Standard Errors
-  return {
-    name: error.name || 'Error',
-    message: error.message,
-    // Critical fields for FluentAPIError
-    statusCode: error.statusCode, 
-    details: error.details,       
-    code: error.code,
-    // Optional: stack trace
-    stack: error.stack
-  };
-}
-
-// Usage Example
-const event = {
-  name: "UPSERT_PRODUCT",
-  retailerId: "YOUR_RETAILER_ID",
-  entityRef: "PC:MASTER:2",
-  entityType: "PRODUCT_CATALOGUE",
-  entitySubtype: "MASTER",
-  rootEntityRef: "PC:MASTER:2",
-  rootEntityType: "PRODUCT_CATALOGUE",
-  attributes: {
-    ref: "G_PROD_WITH_NO_STANDARD",
-    type: "VARIANT",
-    status: "ACTIVE",
-    gtin: "MH01-XS-Orange",
-    name: "Chaz Kangeroo Hoodie-XS-Orange main",
-    summary: "<p>test short description</p>",
-    categoryRefs: ["STANDARD_CATEGORY"],
-    price: [
-      { type: "DEFAULT", currency: "USD", value: "52.000000" },
-      { type: "SPECIAL", currency: "USD", value: "9.000000" }
-    ],
-    taxType: {
-      country: "AU",
-      group: "Tax Group",
-      tariff: "Tax Tariff"
-    }
-  }
-};
-
-try {
-  await client.sendEvent(event);
-} catch (error) {
-  const fullError = extractError(error);
-  console.error('Error Thrown:', JSON.stringify(fullError, null, 2));
-}
-```
-
-**Resulting Output:**
-
-```json
-{
-  "name": "FluentAPIError",
-  "message": "Request failed: 404",
-  "statusCode": 404,
-  "details": "No workflow rule matched this event"
-}
-```
-
-[Full error type documentation →](./modules/error-handling-02-error-types.md)
-
----
-
-## ❓ Where is the Status Code?
-
-The location of the HTTP status code depends on whether the call **Succeeded** or **Failed**.
-
-### Event API (sendEvent)
-
-| Outcome | Where is the Status Code? | Example Value |
-| :--- | :--- | :--- |
-| **✅ Success** | `response.statusCode` | `200`, `201` |
-| **❌ Failure** | `error.statusCode` | `400`, `404`, `500` |
-
-### GraphQL API (graphql)
-
-| Outcome | Where is the Status Code? | Example Value |
-| :--- | :--- | :--- |
-| **✅ Success** | **Not returned** (Implicit 200 OK) | N/A |
-| **⚠️ Execution Error** | **Not returned** (Implicit 200 OK) | N/A |
-| **❌ HTTP Failure** | `error.statusCode` | `500`, `503` |
-
----
-
-## 🔍 Anatomy of an API Call
-
-This section visualizes exactly what goes **IN** and what comes **OUT** of SDK operations.
-
-### 1. Event API Anatomy
-
-**Scenario:** Sending a Product Upsert event.
-
-#### A. The Input (Event Payload)
-```typescript
-const event = {
-  name: "UPSERT_PRODUCT",
-  retailerId: "2",
-  entityRef: "PC:MASTER:2",
-  entityType: "PRODUCT_CATALOGUE",
-  // ...
-};
-```
-
-#### B. The Call
-```typescript
-try {
-  const response = await client.sendEvent(event);
-  console.log('Success:', response);
-} catch (error) {
-  console.error('Error:', extractError(error));
-}
-```
-
-#### C. The Output (Two Possible Outcomes)
-
-| Outcome | Structure Returned / Thrown | Status Code Location |
-| :--- | :--- | :--- |
-| **✅ SUCCESS** | **`EventResponse` Object**<br>Returned by `await` | **`response.statusCode`**<br>(e.g. 200) |
-| **❌ FAILURE** | **`FluentAPIError` Object**<br>Caught in `catch` block | **`error.statusCode`**<br>(e.g. 400) |
-
----
-
-### 2. GraphQL API Anatomy
-
-**Scenario:** Querying an Order by Reference.
-
-#### A. The Input (Query & Variables)
-```typescript
-const query = `
-  query GetOrder($ref: String!) {
-    order(ref: $ref) {
-      id
-      ref
-      status
-    }
-  }
-`;
-
-const variables = {
-  ref: "ORD-123"
-};
-```
-
-#### B. The Call
-```typescript
-try {
-  const response = await client.graphql({ query, variables });
-  console.log('Success:', response.data);
-} catch (error) {
-  console.error('Error:', extractError(error));
-}
-```
-
-#### C. The Output (Three Possible Outcomes)
-
-| Outcome | Structure Returned / Thrown | Status Code Location |
-| :--- | :--- | :--- |
-| **✅ SUCCESS** | **`GraphQLResponse` Object**<br>Returned by `await` | **None**<br>(Implicit 200 OK) |
-| **❌ HTTP FAILURE** | **`FluentAPIError` Object**<br>Caught in `catch` block | **`error.statusCode`**<br>(e.g. 500) |
-| **⚠️ EXECUTION ERROR** | **`GraphQLExecutionError` Object**<br>Caught in `catch` block | **None**<br>(Implicit 200 OK) |
-
----
-
-## Event API Error Handling
-
-### Success Response Structure
-
-```typescript
-interface EventResponse {
-  id?: string;                 // Event ID (if returned)
-  success: boolean;            // Always true for success
-  status?: number;             // Event status from Fluent API (CREATED, COMPLETED, etc.)
-  statusCode?: number;         // HTTP status code (200, 201, 202)
-  message?: string;            // Optional message
-}
-```
-
-### Basic Try-Catch Pattern
-
-```typescript
-import { FluentClient, FluentAPIError, AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
-
-const client = new FluentClient({
-  baseUrl: 'https://api.fluentcommerce.com',
-  clientId: 'YOUR_CLIENT_ID',
-  clientSecret: 'YOUR_CLIENT_SECRET',
-  username: 'YOUR_USERNAME',
-  password: 'YOUR_PASSWORD',
-  retailerId: 'YOUR_RETAILER_ID'
-});
-
-try {
-  // SUCCESS CASE
-  const result = await client.sendEvent({
-    name: 'OrderCancel1',
-    entityRef: 'G_TEST_FC_POSTMAN_34',
-    entityType: 'ORDER',
-    retailerId: '2'
-  }, 'async');
-
-  console.log('✅ Event sent successfully');
-  console.log('HTTP Status:', result.statusCode);    // 200
-  console.log('Success:', result.success);           // true
-  console.log('Event ID:', result.id);               // evt-123 (if available)
-
-} catch (error) {
-  if (error instanceof FluentAPIError) {
-    // API Error (400, 404, 500, etc.)
-    console.error('❌ API Error');
-    console.error('Status:', error.statusCode);      // 400, 404, 500, etc.
-    console.error('Message:', error.message);        // "Request failed: 400"
-    console.error('Details:', error.details);        // Response body
-
-  } else if (error instanceof AuthenticationError) {
-    // Auth failed after 3 retries
-    console.error('❌ Authentication Error');
-    console.error('Message:', error.message);
-    console.error('Status:', error.statusCode);      // 401
-
-  } else {
-    // Unknown error
-    console.error('❌ Unexpected Error:', error);
-  }
-}
-```
-
-### Async Mode - Success Examples
-
-**Input:**
-```json
-{
-  "name": "OrderCancel1",
-  "entityRef": "G_TEST_FC_POSTMAN_34",
-  "entityType": "ORDER",
-  "retailerId": "2"
-}
-```
-
-**Output (Success):**
-```json
-{
-  "success": true,
-  "statusCode": 200
-}
-```
-
-**Code:**
-```typescript
-const result = await client.sendEvent({
-  name: 'OrderCancel1',
-  entityRef: 'G_TEST_FC_POSTMAN_34',
-  entityType: 'ORDER',
-  retailerId: '2'
-}, 'async');
-
-// result.success = true
-// result.statusCode = 200
-```
-
----
-
-### ⚡ SDK Automatic Retry Behavior
-
-> **IMPORTANT:** The SDK automatically retries certain errors WITHOUT your intervention
-
-**✅ Automatically Retried (3 attempts with exponential backoff):**
-- `401 Unauthorized` - Token refresh attempt
-- `500 Internal Server Error` - Transient server issue
-- `503 Service Unavailable` - API temporarily overloaded
-- Network errors - Connection failures
-
-**❌ NOT Retried (Fail Immediately):**
-- `400 Bad Request` - Invalid event payload
-- `404 Not Found` - No workflow matched (sync mode)
-- `422 Unprocessable Entity` - Validation failed
-- All other 4xx errors
-
-**Example:**
-```typescript
-try {
-  await client.sendEvent(event);
-} catch (error) {
-  if (error instanceof FluentAPIError && error.statusCode === 500) {
-    // ⚠️ SDK already retried 3 times with exponential backoff
-    // This error means all retries failed
-    console.error('Server error after 3 automatic retries');
-
-    // You may want to implement additional retry logic here
-    // or send to a dead letter queue
-  }
-}
-```
-
----
-
-### Async Mode - Error Examples
-
-#### Error 1: Invalid Event Name (400)
-
-**Input:**
-```json
-{
-  "name": "InvalidEventName",
-  "entityRef": "TEST-123",
-  "entityType": "ORDER",
-  "retailerId": "2"
-}
-```
-
-**Error Thrown:**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 400",
-  statusCode: 400,
-  details: "Bad Request - Invalid event configuration"
-}
-```
-
-**Handling:**
-```typescript
-try {
-  await client.sendEvent({
-    name: 'InvalidEventName',  // ❌ No workflow configured
-    entityRef: 'TEST-123',
-    entityType: 'ORDER',
-    retailerId: '2'
-  }, 'async');
-} catch (error) {
-  if (error instanceof FluentAPIError && error.statusCode === 400) {
-    console.error('Invalid event configuration');
-    // ⚠️ SDK did NOT retry (4xx = client error)
-    // Fix: Check event name in Rubix workflow configuration
-  }
-}
-```
-
----
-
-#### Error 2: Missing retailerId (SDK Validation)
-
-**Input:**
-```json
-{
-  "name": "TEST.EVENT",
-  "entityRef": "TEST-123",
-  "entityType": "ORDER"
-  // ❌ Missing retailerId
-}
-```
-
-**Error Thrown:**
-```typescript
-FluentValidationError {
-  name: "FluentValidationError",
-  message: "retailerId is required for Event API. Provide it in the event payload or client config.",
-  code: "VALIDATION_ERROR",
-  statusCode: 400
-}
-```
-
-**Key Point**: This error is thrown BEFORE the API call (fail-fast).
-
-**Handling:**
-```typescript
-try {
-  await client.sendEvent({
-    name: 'TEST.EVENT',
-    entityRef: 'TEST-123',
-    entityType: 'ORDER'
-    // ❌ Missing retailerId
-  }, 'async');
-} catch (error) {
-  if (error instanceof Error && error.message.includes('retailerId is required')) {
-    console.error('❌ retailerId validation failed (caught BEFORE API call)');
-    // Fix: Add retailerId to event or client config
-  }
-}
-```
-
----
-
-### Sync Mode - Success and Error Examples
-
-#### Sync Mode Success
-
-**Input:**
-```json
-{
-  "name": "OrderCancel1",
-  "entityRef": "ORDER-SYNC-123",
-  "entityType": "ORDER",
-  "retailerId": "2"
-}
-```
-
-**Output (if workflow configured and succeeds):**
-```json
-{
-  "success": true,
-  "status": "COMPLETED",
-  "statusCode": 201,
-  "message": "Workflow completed successfully"
-}
-```
-
-**Code:**
-```typescript
-const result = await client.sendEvent({
-  name: 'OrderCancel1',
-  entityRef: 'ORDER-SYNC-123',
-  entityType: 'ORDER',
-  retailerId: '2'
-}, 'sync');  // ← Sync mode waits for workflow
-
-console.log('Workflow completed:', result.status);
-console.log('HTTP Status:', result.statusCode);
-```
-
----
-
-#### Sync Mode Error: No Workflow Match (404)
-
-**Input:**
-```json
-{
-  "name": "OrderCancel1",
-  "entityRef": "SYNC-NO-MATCH",
-  "entityType": "ORDER",
-  "retailerId": "2"
-}
-```
-
-**Error Thrown:**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 404",
-  statusCode: 404,
-  details: "No workflow rule matched this event"
-}
-```
-
-**Handling:**
-```typescript
-try {
-  await client.sendEvent({
-    name: 'OrderCancel1',
-    entityRef: 'SYNC-NO-MATCH',
-    entityType: 'ORDER',
-    retailerId: '2'
-  }, 'sync');
-} catch (error) {
-  if (error instanceof FluentAPIError && error.statusCode === 404) {
-    console.error('No workflow rule matched (sync mode detected this)');
-    // ⚠️ Async mode would return 200 (doesn't wait for workflow)
-    // ✅ Sync mode detected the failure immediately
-  }
-}
-```
-
----
-
-### Batch Processing with Per-Event Error Handling
-
-```typescript
-interface EventResult {
-  sku: string;
-  success: boolean;
-  statusCode?: number;
-  error?: string;
-}
-
-async function processProducts(products: Product[]): Promise<EventResult[]> {
-  const results: EventResult[] = [];
-
-  for (const product of products) {
-    try {
-      const response = await client.sendEvent({
-        name: 'PRODUCT.UPSERT',
-        entityType: 'PRODUCT',
-        entityRef: product.sku,
-        retailerId: '2',
-        attributes: product
-      }, 'async');
-
-      // SUCCESS
-      results.push({
-        sku: product.sku,
-        success: true,
-        statusCode: response.statusCode
-      });
-
-      console.log(`✅ ${product.sku} - HTTP ${response.statusCode}`);
-
-    } catch (error) {
-      if (error instanceof FluentAPIError) {
-        // API ERROR (SDK already retried 401/5xx)
-        results.push({
-          sku: product.sku,
-          success: false,
-          error: `HTTP ${error.statusCode}: ${error.message}`
-        });
-
-        console.error(`❌ ${product.sku} - ${error.statusCode}: ${error.message}`);
-
-        // Handle specific error codes
-        if (error.statusCode === 400) {
-          console.error('   → Invalid product data');
-        } else if (error.statusCode === 422) {
-          console.error('   → Validation failed');
-        } else if (error.statusCode === 500) {
-          console.error('   → Server error (SDK already retried 3x)');
-        }
-
-      } else if (error instanceof AuthenticationError) {
-        // AUTH FAILED (after 3 retries)
-        console.error(`❌ Auth failed: ${error.message}`);
-        // Stop processing - credentials are invalid
-        break;
-
-      } else {
-        // UNEXPECTED ERROR
-        results.push({
-          sku: product.sku,
-          success: false,
-          error: error.message
-        });
-      }
-    }
-  }
-
-  return results;
-}
-```
-
----
-
-## GraphQL Error Handling
-
-### Success Response Structure
-
-```typescript
-interface GraphQLResponse {
-  data: any;                   // Query/mutation result
-  errors?: undefined;          // No errors on success
-}
-```
-
-### Error Response Structure
-
-When GraphQL returns errors, SDK throws `GraphQLExecutionError`:
-
-```typescript
-{
-  name: 'GraphQLExecutionError',
-  message: string,             // First error message
-  graphqlErrors: Array<{
-    message: string,
-    locations?: Array<{ line: number, column: number }>,
-    path?: Array<string | number>,
-    extensions?: { ... }
-  }>,
-  query: string,
-  variables?: { ... }
-}
-```
-
-### Basic Try-Catch Pattern
-
-```typescript
-try {
-  // SUCCESS CASE
-  const result = await client.graphql({
-    query: `
-      query GetOrder($ref: String!) {
-        order(ref: $ref) {
-          id
-          ref
-          status
-        }
-      }
-    `,
-    variables: { ref: 'ORDER-123' }
-  });
-
-  console.log('✅ GraphQL query succeeded');
-  console.log('Data:', result.data);
-  console.log('Order:', result.data.order);
-
-} catch (error) {
-  if (error instanceof GraphQLExecutionError) {
-    // GraphQL returned errors
-    console.error('❌ GraphQL Execution Error');
-    console.error('Message:', error.message);
-    console.error('All errors:', error.getErrorMessages());
-    console.error('Query:', error.query);
-
-    // Check for specific errors
-    const errorMessages = error.getErrorMessages();
-    if (errorMessages.some(msg => msg.includes('invalidField'))) {
-      console.error('   → Invalid field in query');
-    }
-
-  } else if (error instanceof FluentAPIError) {
-    // HTTP error (400, 500, etc.)
-    console.error('❌ API Error');
-    console.error('Status:', error.statusCode);
-    console.error('Message:', error.message);
-
-  } else if (error instanceof AuthenticationError) {
-    // Auth failed
-    console.error('❌ Authentication failed');
-
-  } else {
-    console.error('❌ Unexpected error:', error);
-  }
-}
-```
-
-### GraphQL Success Example
-
-**Input:**
-```graphql
-query GetOrder($ref: String!) {
-  order(ref: $ref) {
-    id
-    ref
-    status
-  }
-}
-```
-
-**Variables:**
-```json
-{
-  "ref": "ORDER-123"
-}
-```
-
-**Output (Success):**
-```json
-{
-  "data": {
-    "order": {
-      "id": "ORDER-123",
-      "ref": "ORD-2024-123",
-      "status": "CREATED"
-    }
-  }
-}
-```
-
-**Code:**
-```typescript
-const result = await client.graphql({
-  query: `query GetOrder($ref: String!) { order(ref: $ref) { id ref status } }`,
-  variables: { ref: 'ORDER-123' }
-});
-
-console.log('Order ID:', result.data.order.id);
-console.log('Order Ref:', result.data.order.ref);
-console.log('Order Status:', result.data.order.status);
-```
-
----
-
-### GraphQL Error Examples
-
-#### Error 1: Invalid Field
-
-**Input:**
-```graphql
-query GetOrder {
-  order(ref: "123") {
-    id
-    invalidField  # ❌ Field doesn't exist
-  }
-}
-```
-
-**Error Thrown:**
-```typescript
-GraphQLExecutionError {
-  name: "GraphQLExecutionError",
-  message: "Field \"invalidField\" doesn't exist on type \"Order\"",
-  graphqlErrors: [
-    {
-      message: "Field \"invalidField\" doesn't exist on type \"Order\"",
-      locations: [{ line: 4, column: 5 }],
-      extensions: { ... }
-    }
-  ],
-  query: "query GetOrder { ... }"
-}
-```
-
-**Handling:**
-```typescript
-try {
-  await client.graphql({
-    query: `query GetOrder { order(ref: "123") { id invalidField } }`
-  });
-} catch (error) {
-  if (error instanceof GraphQLExecutionError) {
-    console.error('GraphQL Error:', error.message);
-
-    // Get all error messages
-    const messages = error.getErrorMessages();
-    console.error('All errors:', messages);
-
-    // Check for specific error
-    const errorMessages = error.getErrorMessages();
-    if (errorMessages.some(msg => msg.includes('invalidField'))) {
-      console.error('Invalid field in query - check schema');
-    }
-  }
-}
-```
-
----
-
-#### Error 2: Syntax Error
-
-**Input:**
-```graphql
-query GetOrder {
-  order(ref: "123"  # ❌ Missing closing parenthesis
-    id
-    ref
-  }
-}
-```
-
-**Error Thrown:**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 400",
-  statusCode: 400,
-  details: {
-    errors: [
-      {
-        message: "Syntax Error: Expected ')', found Name 'id'",
-        locations: [{ line: 3, column: 5 }]
-      }
-    ]
-  }
-}
-```
-
-**Note**: Syntax errors throw `FluentAPIError` (400), not `GraphQLExecutionError`.
-
----
-
-### GraphQL with Pagination
-
-```typescript
-try {
-  const result = await client.graphql({
-    query: `
-      query GetOrders {
-        orders(first: 50) {
-          edges {
-            node {
-              id
-              ref
-              status
-            }
-          }
-          pageInfo {
-            hasNextPage
-            endCursor
-          }
-        }
-      }
-    `,
-    pagination: {
-      enabled: true,
-      maxPages: 10,
-      maxRecords: 500
-    }
-  });
-
-  console.log('✅ Fetched', result.data.orders.edges.length, 'orders');
-  console.log('Total pages fetched:', result.extensions?.autoPagination?.totalPages);
-
-} catch (error) {
-  if (error instanceof GraphQLExecutionError) {
-    console.error('GraphQL error during pagination:', error.message);
-  } else if (error instanceof FluentAPIError) {
-    console.error('API error during pagination:', error.statusCode);
-  }
-}
-```
-
----
-
-## Batch API Error Handling
-
-### Success Response Structure
-
-```typescript
-interface FluentBatchResponse {
-  id: string;                  // Batch ID
-  jobId: string;               // Job ID
-  status: string;              // Batch status (CREATED, SUBMITTED, PROCESSING, COMPLETED, FAILED)
-  processedEntities?: number;  // Number of entities processed
-  totalEntities?: number;       // Total entities in batch
-  createdAt?: string;          // ISO timestamp
-  updatedAt?: string;          // ISO timestamp
-  errors?: Array<{            // Failed entity details (if any)
-    code: string;
-    message: string;
-    entityIndex?: number;
-  }>;
-}
-```
-
-### Basic Try-Catch Pattern
-
-```typescript
-try {
-  // SUCCESS CASE
-  const batch = await client.sendBatch('job-123', {
-    entities: [
-      { id: '1', sku: 'SKU-001', name: 'Product 1' },
-      { id: '2', sku: 'SKU-002', name: 'Product 2' }
-    ],
-    action: 'UPSERT'
-  });
-
-  console.log('✅ Batch sent successfully');
-  console.log('Batch ID:', batch.id);
-  console.log('Status:', batch.status);
-
-} catch (error) {
-  if (error instanceof FluentAPIError) {
-    console.error('❌ Batch Error');
-    console.error('Status:', error.statusCode);
-    console.error('Message:', error.message);
-
-    // Common errors
-    if (error.statusCode === 404) {
-      console.error('   → Job not found or expired');
-    } else if (error.statusCode === 400) {
-      console.error('   → Invalid batch payload');
-    } else if (error.statusCode === 500) {
-      console.error('   → Server error (SDK already retried 3x)');
-    }
-  }
-}
-```
-
-### Batch Success Example
-
-**Input:**
-```typescript
-await client.sendBatch('job-123', {
-  entities: [
-    { id: '1', sku: 'SKU-001', name: 'Product 1', price: 19.99 },
-    { id: '2', sku: 'SKU-002', name: 'Product 2', price: 29.99 }
-  ],
-  action: 'UPSERT'
-});
-```
-
-**Output (Success):**
-```json
-{
-  "id": "batch-456",
-  "jobId": "job-123",
-  "status": "CREATED",
-  "processedEntities": 2,
-  "totalEntities": 2
-}
-```
-
----
-
-### Batch Error Examples
-
-#### Error 1: Job Expired (404)
-
-**Input:**
-```typescript
-await client.sendBatch('job-expired-123', {
-  entities: [...],
-  action: 'UPSERT'
-});
-```
-
-**Error Thrown:**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 404",
-  statusCode: 404,
-  details: "Job not found or expired"
-}
-```
-
-**Handling:**
-```typescript
-try {
-  await client.sendBatch(jobId, { entities, action: 'UPSERT' });
-} catch (error) {
-  if (error instanceof FluentAPIError && error.statusCode === 404) {
-    console.error('Job expired - recreating...');
-
-    // Recreate job and retry
-    const newJob = await client.createJob({
-      name: 'inventory-sync',
-      retailerId: '2'
-    });
-
-    await client.sendBatch(newJob.id, { entities, action: 'UPSERT' });
-  }
-}
-```
-
----
-
-#### Error 2: Invalid Batch Payload (400)
-
-**Input:**
-```typescript
-await client.sendBatch('job-123', {
-  entities: [],  // ❌ Empty entities array
-  action: 'UPSERT'
-});
-```
-
-**Error Thrown:**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 400",
-  statusCode: 400,
-  details: "Batch must contain at least one entity"
-}
-```
-
----
-
-### Batch Processing with Retry
-
-```typescript
-async function sendBatchWithRetry(
-  jobId: string,
-  entities: any[],
-  maxRetries: number = 3
-): Promise<FluentBatchResponse> {
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      const batch = await client.sendBatch(jobId, {
-        entities,
-        action: 'UPSERT'
-      });
-
-      console.log(`✅ Batch sent (attempt ${attempt + 1})`);
-      return batch;
-
-    } catch (error) {
-      if (error instanceof FluentAPIError) {
-        if (error.statusCode === 404 && attempt < maxRetries) {
-          // Job expired - recreate
-          console.log(`⚠️ Job expired, recreating... (attempt ${attempt + 1})`);
-
-          const newJob = await client.createJob({
-            name: 'inventory-sync',
-            retailerId: '2'
-          });
-
-          jobId = newJob.id;
-          // Retry with new job ID
-          continue;
-
-        } else if (error.statusCode === 500 && attempt < maxRetries) {
-          // Server error - SDK already retried 3x
-          console.log(`⚠️ Server error, waiting before retry...`);
-          await new Promise(resolve => setTimeout(resolve, 5000));
-          continue;
-
-        } else {
-          // Non-retryable error or max retries reached
-          throw error;
-        }
-      }
-      throw error;
-    }
-  }
-
-  throw new Error('Max retries exceeded');
-}
-```
-
----
-
-## Job API Error Handling
-
-### Success Response Structure
-
-```typescript
-interface FluentJobResponse {
-  id: string;                  // Job ID
-  name: string;                // Job name
-  retailerId: string;
-  status?: string;             // Job status (CREATED, ACTIVE, PROCESSING, COMPLETED, FAILED)
-  meta?: FluentJobMetadata;    // Job metadata (preprocessing, source, etc.)
-  createdAt?: string;          // ISO timestamp
-  updatedAt?: string;          // ISO timestamp
-}
-```
-
-### Basic Try-Catch Pattern
-
-```typescript
-try {
-  // SUCCESS CASE
-  const job = await client.createJob({
-    name: 'inventory-sync',
-    retailerId: '2'
-  });
-
-  console.log('✅ Job created successfully');
-  console.log('Job ID:', job.id);
-  console.log('Status:', job.status);
-  console.log('Created:', job.createdAt);
-
-} catch (error) {
-  if (error instanceof FluentAPIError) {
-    console.error('❌ Job Creation Error');
-    console.error('Status:', error.statusCode);
-    console.error('Message:', error.message);
-
-    if (error.statusCode === 400) {
-      console.error('   → Invalid job payload');
-    } else if (error.statusCode === 403) {
-      console.error('   → Permission denied');
-    }
-  }
-}
-```
-
-### Job Success Example
-
-**Input:**
-```typescript
-await client.createJob({
-  name: 'product-import-batch',
-  retailerId: '2'
-});
-```
-
-**Output (Success):**
-```json
-{
-  "id": "job-789",
-  "name": "product-import-batch",
-  "status": "CREATED",
-  "retailerId": "2",
-  "createdAt": "2025-01-19T10:30:00Z",
-  "updatedAt": "2025-01-19T10:30:00Z"
-}
-```
-
----
-
-### Job Status Checking
-
-**Response Structure:**
-```typescript
-interface FluentJobStatus {
-  id: string;
-  status: string;              // Job status (CREATED, ACTIVE, PROCESSING, COMPLETED, FAILED)
-  progress?: number;           // Progress percentage (0-100)
-  message?: string;            // Status message
-  completedAt?: string;         // ISO timestamp when completed
-  failedAt?: string;           // ISO timestamp when failed
-  errors?: Array<{            // Error details (if failed)
-    code: string;
-    message: string;
-  }>;
-}
-```
-
-**Example:**
-```typescript
-try {
-  const status = await client.getJobStatus('job-789');
-
-  console.log('Job Status:', status.status);
-  console.log('Progress:', status.progress);
-
-  if (status.status === 'FAILED') {
-    console.warn('⚠️ Job failed - check errors');
-    console.error('Errors:', status.errors);
-  }
-
-} catch (error) {
-  if (error instanceof FluentAPIError && error.statusCode === 404) {
-    console.error('Job not found');
-  }
-}
-```
-
----
-
-## Common Patterns
-
-### Pattern 1: Centralized Error Handler
-
-```typescript
-function handleSDKError(error: unknown, context: string): void {
-  if (error instanceof FluentAPIError) {
-    console.error(`[${context}] API Error:`, {
-      status: error.statusCode,
-      message: error.message,
-      details: error.details
-    });
-
-    // Log to monitoring service
-    logger.error('Fluent API Error', {
-      context,
-      status: error.statusCode,
-      message: error.message
-    });
-
-  } else if (error instanceof GraphQLExecutionError) {
-    console.error(`[${context}] GraphQL Error:`, {
-      message: error.message,
-      errors: error.getErrorMessages(),
-      query: error.query
-    });
-
-    logger.error('GraphQL Execution Error', {
-      context,
-      errors: error.getErrorMessages()
-    });
-
-  } else if (error instanceof AuthenticationError) {
-    console.error(`[${context}] Auth Error:`, {
-      message: error.message,
-      status: error.statusCode
-    });
-
-    // Alert - credentials may be invalid
-    alertService.send('Fluent Auth Failure', error.message);
-
-  } else {
-    console.error(`[${context}] Unexpected Error:`, error);
-    logger.error('Unexpected SDK Error', { context, error });
-  }
-}
-
-// Usage
-try {
-  await client.sendEvent(event);
-} catch (error) {
-  handleSDKError(error, 'Event API');
-  throw error; // Re-throw if needed
-}
-```
-
----
-
-### Pattern 2: Retry with Backoff
-
-```typescript
-async function retryWithBackoff<T>(
-  operation: () => Promise<T>,
-  maxRetries: number = 3,
-  baseDelay: number = 1000
-): Promise<T> {
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await operation();
-    } catch (error) {
-      if (error instanceof FluentAPIError) {
-        // Only retry 5xx server errors
-        if (error.statusCode >= 500 && attempt < maxRetries) {
-          const delay = baseDelay * Math.pow(2, attempt);
-          console.log(`⚠️ Server error, retrying in ${delay}ms...`);
-          await new Promise(resolve => setTimeout(resolve, delay));
-          continue;
-        }
-      }
-      throw error;
-    }
-  }
-  throw new Error('Max retries exceeded');
-}
-
-// Usage
-const result = await retryWithBackoff(
-  () => client.sendEvent(event),
-  3,
-  1000
-);
-```
-
----
-
-### Pattern 3: Batch with Dead Letter Queue
-
-```typescript
-interface ProcessingResult {
-  successful: any[];
-  failed: Array<{ item: any; error: string }>;
-}
-
-async function processBatchWithDLQ(
-  items: any[]
-): Promise<ProcessingResult> {
-  const result: ProcessingResult = {
-    successful: [],
-    failed: []
-  };
-
-  for (const item of items) {
-    try {
-      const response = await client.sendEvent({
-        name: 'PRODUCT.UPSERT',
-        entityType: 'PRODUCT',
-        entityRef: item.sku,
-        retailerId: '2',
-        attributes: item
-      });
-
-      result.successful.push(item);
-
-    } catch (error) {
-      if (error instanceof FluentAPIError) {
-        // Add to dead letter queue
-        result.failed.push({
-          item,
-          error: `HTTP ${error.statusCode}: ${error.message}`
-        });
-
-        // Log to DLQ for manual review
-        await deadLetterQueue.add({
-          item,
-          error: error.message,
-          status: error.statusCode,
-          timestamp: new Date().toISOString()
-        });
-      }
-    }
-  }
-
-  return result;
-}
-```
-
----
-
-## Live Examples
-
-### Test Environment
-
-```yaml
-Base URL: https://api.fluentcommerce.com
-Retailer ID: YOUR_RETAILER_ID
-Client ID: YOUR_CLIENT_ID
-```
-
-### Example 1: Event API Success
-
-**Code:**
-```typescript
-const client = new FluentClient({
-  baseUrl: 'https://api.fluentcommerce.com',
-  clientId: 'YOUR_CLIENT_ID',
-  clientSecret: 'YOUR_CLIENT_SECRET',
-  username: 'YOUR_USERNAME',
-  password: 'YOUR_PASSWORD',
-  retailerId: 'YOUR_RETAILER_ID'
-});
-
-const result = await client.sendEvent({
-  name: 'OrderCancel1',
-  entityRef: 'G_TEST_FC_POSTMAN_34',
-  entityType: 'ORDER',
-  retailerId: '2'
-}, 'async');
-
-console.log('Success:', result.success);        // true
-console.log('HTTP Status:', result.statusCode); // 200
-```
-
-**Console Output:**
-```
-Success: true
-HTTP Status: 200
-```
-
----
-
-### Example 2: Event API Error (400)
-
-**Code:**
-```typescript
-try {
-  await client.sendEvent({
-    name: 'InvalidEventName',
-    entityRef: 'TEST-123',
-    entityType: 'ORDER',
-    retailerId: '2'
-  }, 'async');
-} catch (error) {
-  if (error instanceof FluentAPIError) {
-    console.error('Error Status:', error.statusCode);
-    console.error('Error Message:', error.message);
-  }
-}
-```
-
-**Console Output:**
-```
-Error Status: 400
-Error Message: Request failed: 400
-```
-
----
-
-### Example 3: Sync Mode - No Workflow Match (404)
-
-**Code:**
-```typescript
-try {
-  await client.sendEvent({
-    name: 'OrderCancel1',
-    entityRef: 'SYNC-NO-MATCH',
-    entityType: 'ORDER',
-    retailerId: '2'
-  }, 'sync');
-} catch (error) {
-  if (error instanceof FluentAPIError) {
-    console.error('Sync mode detected workflow failure');
-    console.error('Status:', error.statusCode);  // 404
-  }
-}
-```
-
-**Console Output:**
-```
-Sync mode detected workflow failure
-Status: 404
-```
-
----
-
-## Summary Table
-
-| API | Success Type | Error Type | SDK Retries | Notes |
-|-----|-------------|------------|-------------|-------|
-| **Event API** | `EventResponse` | `FluentAPIError`, `AuthenticationError` | ✅ 401 (3x), 5xx (3x) | Async = fast, Sync = detects workflow errors |
-| **GraphQL** | `GraphQLResponse` | `GraphQLExecutionError`, `FluentAPIError`, `AuthenticationError` | ✅ 401 (3x), 5xx (3x) | GraphQL errors vs HTTP errors |
-| **Batch API** | `FluentBatchResponse` | `FluentAPIError`, `AuthenticationError` | ✅ 401 (3x), 5xx (3x) | Watch for job expiry (404) |
-| **Job API** | `FluentJobResponse` | `FluentAPIError`, `AuthenticationError` | ✅ 401 (3x), 5xx (3x) | Jobs expire after 1 hour |
-
----
-
-## Quick Reference
-
-### When to Use Try-Catch
-
-✅ **Always use try-catch** for:
-- `sendEvent()`
-- `graphql()`
-- `sendBatch()`
-- `createJob()`
-- `getJobStatus()`
-- Any SDK method that makes API calls
-
-### Error Handling Checklist
-
-- [ ] Catch `FluentAPIError` for HTTP errors
-- [ ] Catch `AuthenticationError` for auth failures
-- [ ] Catch `GraphQLExecutionError` for GraphQL errors
-- [ ] Check `error.statusCode` to determine error type
-- [ ] Log errors with context for debugging
-- [ ] Implement retry logic for transient errors (5xx)
-- [ ] Use dead letter queue for persistent failures
-- [ ] Alert on authentication failures
-
----
-
-**SDK Version**: 0.1.46
-**Date**: 2025-01-19
+# Comprehensive Error Handling Guide
+
+> **Complete guide** to error handling across GraphQL, Event API, Batch API, and Job API with live examples
+
+## Table of Contents
+
+1. [Error Types Overview](#error-types-overview)
+2. [Where is the Status Code?](#where-is-the-status-code)
+3. [Anatomy of an API Call](#anatomy-of-an-api-call)
+4. [Event API Error Handling](#event-api-error-handling)
+5. [GraphQL Error Handling](#graphql-error-handling)
+6. [Batch API Error Handling](#batch-api-error-handling)
+7. [Job API Error Handling](#job-api-error-handling)
+8. [Common Patterns](#common-patterns)
+9. [Live Examples](#live-examples)
+
+---
+
+## Error Types Overview
+
+> **📚 For complete error type reference**, see [Module 2: Error Types & Codes](./modules/error-handling-02-error-types.md)
+
+**Quick Summary:**
+
+| Error Type | When Thrown | HTTP Status | Auto-Retry |
+|------------|-------------|-------------|------------|
+| **FluentAPIError** | HTTP errors (4xx, 5xx) | 400, 404, 500, etc. | ✅ Yes (401, 5xx) |
+| **AuthenticationError** | OAuth2 auth fails after 3 retries | 401 | N/A (already retried) |
+| **GraphQLExecutionError** | GraphQL returns errors in response | 200 (with errors) | ❌ No |
+
+### ⚡ How to Capture the Full Error Object
+
+Standard logging (like `JSON.stringify(error)`) often misses custom fields. Use this helper to capture the full structure for your logs:
+
+```typescript
+/**
+ * Helper to extract full error details including HTTP status and response body
+ */
+function extractError(error: any) {
+  // 1. Use toJSON() if available (e.g. GraphQLExecutionError, IngestionError)
+  if (typeof error.toJSON === 'function') {
+    return error.toJSON();
+  }
+
+  // 2. Manual extraction for FluentAPIError / Standard Errors
+  return {
+    name: error.name || 'Error',
+    message: error.message,
+    // Critical fields for FluentAPIError
+    statusCode: error.statusCode, 
+    details: error.details,       
+    code: error.code,
+    // Optional: stack trace
+    stack: error.stack
+  };
+}
+
+// Usage Example
+const event = {
+  name: "UPSERT_PRODUCT",
+  retailerId: "YOUR_RETAILER_ID",
+  entityRef: "PC:MASTER:2",
+  entityType: "PRODUCT_CATALOGUE",
+  entitySubtype: "MASTER",
+  rootEntityRef: "PC:MASTER:2",
+  rootEntityType: "PRODUCT_CATALOGUE",
+  attributes: {
+    ref: "G_PROD_WITH_NO_STANDARD",
+    type: "VARIANT",
+    status: "ACTIVE",
+    gtin: "MH01-XS-Orange",
+    name: "Chaz Kangeroo Hoodie-XS-Orange main",
+    summary: "<p>test short description</p>",
+    categoryRefs: ["STANDARD_CATEGORY"],
+    price: [
+      { type: "DEFAULT", currency: "USD", value: "52.000000" },
+      { type: "SPECIAL", currency: "USD", value: "9.000000" }
+    ],
+    taxType: {
+      country: "AU",
+      group: "Tax Group",
+      tariff: "Tax Tariff"
+    }
+  }
+};
+
+try {
+  await client.sendEvent(event);
+} catch (error) {
+  const fullError = extractError(error);
+  console.error('Error Thrown:', JSON.stringify(fullError, null, 2));
+}
+```
+
+**Resulting Output:**
+
+```json
+{
+  "name": "FluentAPIError",
+  "message": "Request failed: 404",
+  "statusCode": 404,
+  "details": "No workflow rule matched this event"
+}
+```
+
+[Full error type documentation →](./modules/error-handling-02-error-types.md)
+
+---
+
+## ❓ Where is the Status Code?
+
+The location of the HTTP status code depends on whether the call **Succeeded** or **Failed**.
+
+### Event API (sendEvent)
+
+| Outcome | Where is the Status Code? | Example Value |
+| :--- | :--- | :--- |
+| **✅ Success** | `response.statusCode` | `200`, `201` |
+| **❌ Failure** | `error.statusCode` | `400`, `404`, `500` |
+
+### GraphQL API (graphql)
+
+| Outcome | Where is the Status Code? | Example Value |
+| :--- | :--- | :--- |
+| **✅ Success** | **Not returned** (Implicit 200 OK) | N/A |
+| **⚠️ Execution Error** | **Not returned** (Implicit 200 OK) | N/A |
+| **❌ HTTP Failure** | `error.statusCode` | `500`, `503` |
+
+---
+
+## 🔍 Anatomy of an API Call
+
+This section visualizes exactly what goes **IN** and what comes **OUT** of SDK operations.
+
+### 1. Event API Anatomy
+
+**Scenario:** Sending a Product Upsert event.
+
+#### A. The Input (Event Payload)
+```typescript
+const event = {
+  name: "UPSERT_PRODUCT",
+  retailerId: "2",
+  entityRef: "PC:MASTER:2",
+  entityType: "PRODUCT_CATALOGUE",
+  // ...
+};
+```
+
+#### B. The Call
+```typescript
+try {
+  const response = await client.sendEvent(event);
+  console.log('Success:', response);
+} catch (error) {
+  console.error('Error:', extractError(error));
+}
+```
+
+#### C. The Output (Two Possible Outcomes)
+
+| Outcome | Structure Returned / Thrown | Status Code Location |
+| :--- | :--- | :--- |
+| **✅ SUCCESS** | **`EventResponse` Object**<br>Returned by `await` | **`response.statusCode`**<br>(e.g. 200) |
+| **❌ FAILURE** | **`FluentAPIError` Object**<br>Caught in `catch` block | **`error.statusCode`**<br>(e.g. 400) |
+
+---
+
+### 2. GraphQL API Anatomy
+
+**Scenario:** Querying an Order by Reference.
+
+#### A. The Input (Query & Variables)
+```typescript
+const query = `
+  query GetOrder($ref: String!) {
+    order(ref: $ref) {
+      id
+      ref
+      status
+    }
+  }
+`;
+
+const variables = {
+  ref: "ORD-123"
+};
+```
+
+#### B. The Call
+```typescript
+try {
+  const response = await client.graphql({ query, variables });
+  console.log('Success:', response.data);
+} catch (error) {
+  console.error('Error:', extractError(error));
+}
+```
+
+#### C. The Output (Three Possible Outcomes)
+
+| Outcome | Structure Returned / Thrown | Status Code Location |
+| :--- | :--- | :--- |
+| **✅ SUCCESS** | **`GraphQLResponse` Object**<br>Returned by `await` | **None**<br>(Implicit 200 OK) |
+| **❌ HTTP FAILURE** | **`FluentAPIError` Object**<br>Caught in `catch` block | **`error.statusCode`**<br>(e.g. 500) |
+| **⚠️ EXECUTION ERROR** | **`GraphQLExecutionError` Object**<br>Caught in `catch` block | **None**<br>(Implicit 200 OK) |
+
+---
+
+## Event API Error Handling
+
+### Success Response Structure
+
+```typescript
+interface EventResponse {
+  id?: string;                 // Event ID (if returned)
+  success: boolean;            // Always true for success
+  status?: number;             // Event status from Fluent API (CREATED, COMPLETED, etc.)
+  statusCode?: number;         // HTTP status code (200, 201, 202)
+  message?: string;            // Optional message
+}
+```
+
+### Basic Try-Catch Pattern
+
+```typescript
+import { FluentClient, FluentAPIError, AuthenticationError } from '@fluentcommerce/fc-connect-sdk';
+
+const client = new FluentClient({
+  baseUrl: 'https://api.fluentcommerce.com',
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  username: 'YOUR_USERNAME',
+  password: 'YOUR_PASSWORD',
+  retailerId: 'YOUR_RETAILER_ID'
+});
+
+try {
+  // SUCCESS CASE
+  const result = await client.sendEvent({
+    name: 'OrderCancel1',
+    entityRef: 'G_TEST_FC_POSTMAN_34',
+    entityType: 'ORDER',
+    retailerId: '2'
+  }, 'async');
+
+  console.log('✅ Event sent successfully');
+  console.log('HTTP Status:', result.statusCode);    // 200
+  console.log('Success:', result.success);           // true
+  console.log('Event ID:', result.id);               // evt-123 (if available)
+
+} catch (error) {
+  if (error instanceof FluentAPIError) {
+    // API Error (400, 404, 500, etc.)
+    console.error('❌ API Error');
+    console.error('Status:', error.statusCode);      // 400, 404, 500, etc.
+    console.error('Message:', error.message);        // "Request failed: 400"
+    console.error('Details:', error.details);        // Response body
+
+  } else if (error instanceof AuthenticationError) {
+    // Auth failed after 3 retries
+    console.error('❌ Authentication Error');
+    console.error('Message:', error.message);
+    console.error('Status:', error.statusCode);      // 401
+
+  } else {
+    // Unknown error
+    console.error('❌ Unexpected Error:', error);
+  }
+}
+```
+
+### Async Mode - Success Examples
+
+**Input:**
+```json
+{
+  "name": "OrderCancel1",
+  "entityRef": "G_TEST_FC_POSTMAN_34",
+  "entityType": "ORDER",
+  "retailerId": "2"
+}
+```
+
+**Output (Success):**
+```json
+{
+  "success": true,
+  "statusCode": 200
+}
+```
+
+**Code:**
+```typescript
+const result = await client.sendEvent({
+  name: 'OrderCancel1',
+  entityRef: 'G_TEST_FC_POSTMAN_34',
+  entityType: 'ORDER',
+  retailerId: '2'
+}, 'async');
+
+// result.success = true
+// result.statusCode = 200
+```
+
+---
+
+### ⚡ SDK Automatic Retry Behavior
+
+> **IMPORTANT:** The SDK automatically retries certain errors WITHOUT your intervention
+
+**✅ Automatically Retried (3 attempts with exponential backoff):**
+- `401 Unauthorized` - Token refresh attempt
+- `500 Internal Server Error` - Transient server issue
+- `503 Service Unavailable` - API temporarily overloaded
+- Network errors - Connection failures
+
+**❌ NOT Retried (Fail Immediately):**
+- `400 Bad Request` - Invalid event payload
+- `404 Not Found` - No workflow matched (sync mode)
+- `422 Unprocessable Entity` - Validation failed
+- All other 4xx errors
+
+**Example:**
+```typescript
+try {
+  await client.sendEvent(event);
+} catch (error) {
+  if (error instanceof FluentAPIError && error.statusCode === 500) {
+    // ⚠️ SDK already retried 3 times with exponential backoff
+    // This error means all retries failed
+    console.error('Server error after 3 automatic retries');
+
+    // You may want to implement additional retry logic here
+    // or send to a dead letter queue
+  }
+}
+```
+
+---
+
+### Async Mode - Error Examples
+
+#### Error 1: Invalid Event Name (400)
+
+**Input:**
+```json
+{
+  "name": "InvalidEventName",
+  "entityRef": "TEST-123",
+  "entityType": "ORDER",
+  "retailerId": "2"
+}
+```
+
+**Error Thrown:**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 400",
+  statusCode: 400,
+  details: "Bad Request - Invalid event configuration"
+}
+```
+
+**Handling:**
+```typescript
+try {
+  await client.sendEvent({
+    name: 'InvalidEventName',  // ❌ No workflow configured
+    entityRef: 'TEST-123',
+    entityType: 'ORDER',
+    retailerId: '2'
+  }, 'async');
+} catch (error) {
+  if (error instanceof FluentAPIError && error.statusCode === 400) {
+    console.error('Invalid event configuration');
+    // ⚠️ SDK did NOT retry (4xx = client error)
+    // Fix: Check event name in Rubix workflow configuration
+  }
+}
+```
+
+---
+
+#### Error 2: Missing retailerId (SDK Validation)
+
+**Input:**
+```json
+{
+  "name": "TEST.EVENT",
+  "entityRef": "TEST-123",
+  "entityType": "ORDER"
+  // ❌ Missing retailerId
+}
+```
+
+**Error Thrown:**
+```typescript
+FluentValidationError {
+  name: "FluentValidationError",
+  message: "retailerId is required for Event API. Provide it in the event payload or client config.",
+  code: "VALIDATION_ERROR",
+  statusCode: 400
+}
+```
+
+**Key Point**: This error is thrown BEFORE the API call (fail-fast).
+
+**Handling:**
+```typescript
+try {
+  await client.sendEvent({
+    name: 'TEST.EVENT',
+    entityRef: 'TEST-123',
+    entityType: 'ORDER'
+    // ❌ Missing retailerId
+  }, 'async');
+} catch (error) {
+  if (error instanceof Error && error.message.includes('retailerId is required')) {
+    console.error('❌ retailerId validation failed (caught BEFORE API call)');
+    // Fix: Add retailerId to event or client config
+  }
+}
+```
+
+---
+
+### Sync Mode - Success and Error Examples
+
+#### Sync Mode Success
+
+**Input:**
+```json
+{
+  "name": "OrderCancel1",
+  "entityRef": "ORDER-SYNC-123",
+  "entityType": "ORDER",
+  "retailerId": "2"
+}
+```
+
+**Output (if workflow configured and succeeds):**
+```json
+{
+  "success": true,
+  "status": "COMPLETED",
+  "statusCode": 201,
+  "message": "Workflow completed successfully"
+}
+```
+
+**Code:**
+```typescript
+const result = await client.sendEvent({
+  name: 'OrderCancel1',
+  entityRef: 'ORDER-SYNC-123',
+  entityType: 'ORDER',
+  retailerId: '2'
+}, 'sync');  // ← Sync mode waits for workflow
+
+console.log('Workflow completed:', result.status);
+console.log('HTTP Status:', result.statusCode);
+```
+
+---
+
+#### Sync Mode Error: No Workflow Match (404)
+
+**Input:**
+```json
+{
+  "name": "OrderCancel1",
+  "entityRef": "SYNC-NO-MATCH",
+  "entityType": "ORDER",
+  "retailerId": "2"
+}
+```
+
+**Error Thrown:**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 404",
+  statusCode: 404,
+  details: "No workflow rule matched this event"
+}
+```
+
+**Handling:**
+```typescript
+try {
+  await client.sendEvent({
+    name: 'OrderCancel1',
+    entityRef: 'SYNC-NO-MATCH',
+    entityType: 'ORDER',
+    retailerId: '2'
+  }, 'sync');
+} catch (error) {
+  if (error instanceof FluentAPIError && error.statusCode === 404) {
+    console.error('No workflow rule matched (sync mode detected this)');
+    // ⚠️ Async mode would return 200 (doesn't wait for workflow)
+    // ✅ Sync mode detected the failure immediately
+  }
+}
+```
+
+---
+
+### Batch Processing with Per-Event Error Handling
+
+```typescript
+interface EventResult {
+  sku: string;
+  success: boolean;
+  statusCode?: number;
+  error?: string;
+}
+
+async function processProducts(products: Product[]): Promise<EventResult[]> {
+  const results: EventResult[] = [];
+
+  for (const product of products) {
+    try {
+      const response = await client.sendEvent({
+        name: 'PRODUCT.UPSERT',
+        entityType: 'PRODUCT',
+        entityRef: product.sku,
+        retailerId: '2',
+        attributes: product
+      }, 'async');
+
+      // SUCCESS
+      results.push({
+        sku: product.sku,
+        success: true,
+        statusCode: response.statusCode
+      });
+
+      console.log(`✅ ${product.sku} - HTTP ${response.statusCode}`);
+
+    } catch (error) {
+      if (error instanceof FluentAPIError) {
+        // API ERROR (SDK already retried 401/5xx)
+        results.push({
+          sku: product.sku,
+          success: false,
+          error: `HTTP ${error.statusCode}: ${error.message}`
+        });
+
+        console.error(`❌ ${product.sku} - ${error.statusCode}: ${error.message}`);
+
+        // Handle specific error codes
+        if (error.statusCode === 400) {
+          console.error('   → Invalid product data');
+        } else if (error.statusCode === 422) {
+          console.error('   → Validation failed');
+        } else if (error.statusCode === 500) {
+          console.error('   → Server error (SDK already retried 3x)');
+        }
+
+      } else if (error instanceof AuthenticationError) {
+        // AUTH FAILED (after 3 retries)
+        console.error(`❌ Auth failed: ${error.message}`);
+        // Stop processing - credentials are invalid
+        break;
+
+      } else {
+        // UNEXPECTED ERROR
+        results.push({
+          sku: product.sku,
+          success: false,
+          error: error.message
+        });
+      }
+    }
+  }
+
+  return results;
+}
+```
+
+---
+
+## GraphQL Error Handling
+
+### Success Response Structure
+
+```typescript
+interface GraphQLResponse {
+  data: any;                   // Query/mutation result
+  errors?: undefined;          // No errors on success
+}
+```
+
+### Error Response Structure
+
+When GraphQL returns errors, SDK throws `GraphQLExecutionError`:
+
+```typescript
+{
+  name: 'GraphQLExecutionError',
+  message: string,             // First error message
+  graphqlErrors: Array<{
+    message: string,
+    locations?: Array<{ line: number, column: number }>,
+    path?: Array<string | number>,
+    extensions?: { ... }
+  }>,
+  query: string,
+  variables?: { ... }
+}
+```
+
+### Basic Try-Catch Pattern
+
+```typescript
+try {
+  // SUCCESS CASE
+  const result = await client.graphql({
+    query: `
+      query GetOrder($ref: String!) {
+        order(ref: $ref) {
+          id
+          ref
+          status
+        }
+      }
+    `,
+    variables: { ref: 'ORDER-123' }
+  });
+
+  console.log('✅ GraphQL query succeeded');
+  console.log('Data:', result.data);
+  console.log('Order:', result.data.order);
+
+} catch (error) {
+  if (error instanceof GraphQLExecutionError) {
+    // GraphQL returned errors
+    console.error('❌ GraphQL Execution Error');
+    console.error('Message:', error.message);
+    console.error('All errors:', error.getErrorMessages());
+    console.error('Query:', error.query);
+
+    // Check for specific errors
+    const errorMessages = error.getErrorMessages();
+    if (errorMessages.some(msg => msg.includes('invalidField'))) {
+      console.error('   → Invalid field in query');
+    }
+
+  } else if (error instanceof FluentAPIError) {
+    // HTTP error (400, 500, etc.)
+    console.error('❌ API Error');
+    console.error('Status:', error.statusCode);
+    console.error('Message:', error.message);
+
+  } else if (error instanceof AuthenticationError) {
+    // Auth failed
+    console.error('❌ Authentication failed');
+
+  } else {
+    console.error('❌ Unexpected error:', error);
+  }
+}
+```
+
+### GraphQL Success Example
+
+**Input:**
+```graphql
+query GetOrder($ref: String!) {
+  order(ref: $ref) {
+    id
+    ref
+    status
+  }
+}
+```
+
+**Variables:**
+```json
+{
+  "ref": "ORDER-123"
+}
+```
+
+**Output (Success):**
+```json
+{
+  "data": {
+    "order": {
+      "id": "ORDER-123",
+      "ref": "ORD-2024-123",
+      "status": "CREATED"
+    }
+  }
+}
+```
+
+**Code:**
+```typescript
+const result = await client.graphql({
+  query: `query GetOrder($ref: String!) { order(ref: $ref) { id ref status } }`,
+  variables: { ref: 'ORDER-123' }
+});
+
+console.log('Order ID:', result.data.order.id);
+console.log('Order Ref:', result.data.order.ref);
+console.log('Order Status:', result.data.order.status);
+```
+
+---
+
+### GraphQL Error Examples
+
+#### Error 1: Invalid Field
+
+**Input:**
+```graphql
+query GetOrder {
+  order(ref: "123") {
+    id
+    invalidField  # ❌ Field doesn't exist
+  }
+}
+```
+
+**Error Thrown:**
+```typescript
+GraphQLExecutionError {
+  name: "GraphQLExecutionError",
+  message: "Field \"invalidField\" doesn't exist on type \"Order\"",
+  graphqlErrors: [
+    {
+      message: "Field \"invalidField\" doesn't exist on type \"Order\"",
+      locations: [{ line: 4, column: 5 }],
+      extensions: { ... }
+    }
+  ],
+  query: "query GetOrder { ... }"
+}
+```
+
+**Handling:**
+```typescript
+try {
+  await client.graphql({
+    query: `query GetOrder { order(ref: "123") { id invalidField } }`
+  });
+} catch (error) {
+  if (error instanceof GraphQLExecutionError) {
+    console.error('GraphQL Error:', error.message);
+
+    // Get all error messages
+    const messages = error.getErrorMessages();
+    console.error('All errors:', messages);
+
+    // Check for specific error
+    const errorMessages = error.getErrorMessages();
+    if (errorMessages.some(msg => msg.includes('invalidField'))) {
+      console.error('Invalid field in query - check schema');
+    }
+  }
+}
+```
+
+---
+
+#### Error 2: Syntax Error
+
+**Input:**
+```graphql
+query GetOrder {
+  order(ref: "123"  # ❌ Missing closing parenthesis
+    id
+    ref
+  }
+}
+```
+
+**Error Thrown:**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 400",
+  statusCode: 400,
+  details: {
+    errors: [
+      {
+        message: "Syntax Error: Expected ')', found Name 'id'",
+        locations: [{ line: 3, column: 5 }]
+      }
+    ]
+  }
+}
+```
+
+**Note**: Syntax errors throw `FluentAPIError` (400), not `GraphQLExecutionError`.
+
+---
+
+### GraphQL with Pagination
+
+```typescript
+try {
+  const result = await client.graphql({
+    query: `
+      query GetOrders {
+        orders(first: 50) {
+          edges {
+            node {
+              id
+              ref
+              status
+            }
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    `,
+    pagination: {
+      enabled: true,
+      maxPages: 10,
+      maxRecords: 500
+    }
+  });
+
+  console.log('✅ Fetched', result.data.orders.edges.length, 'orders');
+  console.log('Total pages fetched:', result.extensions?.autoPagination?.totalPages);
+
+} catch (error) {
+  if (error instanceof GraphQLExecutionError) {
+    console.error('GraphQL error during pagination:', error.message);
+  } else if (error instanceof FluentAPIError) {
+    console.error('API error during pagination:', error.statusCode);
+  }
+}
+```
+
+---
+
+## Batch API Error Handling
+
+### Success Response Structure
+
+```typescript
+interface FluentBatchResponse {
+  id: string;                  // Batch ID
+  jobId: string;               // Job ID
+  status: string;              // Batch status (CREATED, SUBMITTED, PROCESSING, COMPLETED, FAILED)
+  processedEntities?: number;  // Number of entities processed
+  totalEntities?: number;       // Total entities in batch
+  createdAt?: string;          // ISO timestamp
+  updatedAt?: string;          // ISO timestamp
+  errors?: Array<{            // Failed entity details (if any)
+    code: string;
+    message: string;
+    entityIndex?: number;
+  }>;
+}
+```
+
+### Basic Try-Catch Pattern
+
+```typescript
+try {
+  // SUCCESS CASE
+  const batch = await client.sendBatch('job-123', {
+    entities: [
+      { id: '1', sku: 'SKU-001', name: 'Product 1' },
+      { id: '2', sku: 'SKU-002', name: 'Product 2' }
+    ],
+    action: 'UPSERT'
+  });
+
+  console.log('✅ Batch sent successfully');
+  console.log('Batch ID:', batch.id);
+  console.log('Status:', batch.status);
+
+} catch (error) {
+  if (error instanceof FluentAPIError) {
+    console.error('❌ Batch Error');
+    console.error('Status:', error.statusCode);
+    console.error('Message:', error.message);
+
+    // Common errors
+    if (error.statusCode === 404) {
+      console.error('   → Job not found or expired');
+    } else if (error.statusCode === 400) {
+      console.error('   → Invalid batch payload');
+    } else if (error.statusCode === 500) {
+      console.error('   → Server error (SDK already retried 3x)');
+    }
+  }
+}
+```
+
+### Batch Success Example
+
+**Input:**
+```typescript
+await client.sendBatch('job-123', {
+  entities: [
+    { id: '1', sku: 'SKU-001', name: 'Product 1', price: 19.99 },
+    { id: '2', sku: 'SKU-002', name: 'Product 2', price: 29.99 }
+  ],
+  action: 'UPSERT'
+});
+```
+
+**Output (Success):**
+```json
+{
+  "id": "batch-456",
+  "jobId": "job-123",
+  "status": "CREATED",
+  "processedEntities": 2,
+  "totalEntities": 2
+}
+```
+
+---
+
+### Batch Error Examples
+
+#### Error 1: Job Expired (404)
+
+**Input:**
+```typescript
+await client.sendBatch('job-expired-123', {
+  entities: [...],
+  action: 'UPSERT'
+});
+```
+
+**Error Thrown:**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 404",
+  statusCode: 404,
+  details: "Job not found or expired"
+}
+```
+
+**Handling:**
+```typescript
+try {
+  await client.sendBatch(jobId, { entities, action: 'UPSERT' });
+} catch (error) {
+  if (error instanceof FluentAPIError && error.statusCode === 404) {
+    console.error('Job expired - recreating...');
+
+    // Recreate job and retry
+    const newJob = await client.createJob({
+      name: 'inventory-sync',
+      retailerId: '2'
+    });
+
+    await client.sendBatch(newJob.id, { entities, action: 'UPSERT' });
+  }
+}
+```
+
+---
+
+#### Error 2: Invalid Batch Payload (400)
+
+**Input:**
+```typescript
+await client.sendBatch('job-123', {
+  entities: [],  // ❌ Empty entities array
+  action: 'UPSERT'
+});
+```
+
+**Error Thrown:**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 400",
+  statusCode: 400,
+  details: "Batch must contain at least one entity"
+}
+```
+
+---
+
+### Batch Processing with Retry
+
+```typescript
+async function sendBatchWithRetry(
+  jobId: string,
+  entities: any[],
+  maxRetries: number = 3
+): Promise<FluentBatchResponse> {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const batch = await client.sendBatch(jobId, {
+        entities,
+        action: 'UPSERT'
+      });
+
+      console.log(`✅ Batch sent (attempt ${attempt + 1})`);
+      return batch;
+
+    } catch (error) {
+      if (error instanceof FluentAPIError) {
+        if (error.statusCode === 404 && attempt < maxRetries) {
+          // Job expired - recreate
+          console.log(`⚠️ Job expired, recreating... (attempt ${attempt + 1})`);
+
+          const newJob = await client.createJob({
+            name: 'inventory-sync',
+            retailerId: '2'
+          });
+
+          jobId = newJob.id;
+          // Retry with new job ID
+          continue;
+
+        } else if (error.statusCode === 500 && attempt < maxRetries) {
+          // Server error - SDK already retried 3x
+          console.log(`⚠️ Server error, waiting before retry...`);
+          await new Promise(resolve => setTimeout(resolve, 5000));
+          continue;
+
+        } else {
+          // Non-retryable error or max retries reached
+          throw error;
+        }
+      }
+      throw error;
+    }
+  }
+
+  throw new Error('Max retries exceeded');
+}
+```
+
+---
+
+## Job API Error Handling
+
+### Success Response Structure
+
+```typescript
+interface FluentJobResponse {
+  id: string;                  // Job ID
+  name: string;                // Job name
+  retailerId: string;
+  status?: string;             // Job status (CREATED, ACTIVE, PROCESSING, COMPLETED, FAILED)
+  meta?: FluentJobMetadata;    // Job metadata (preprocessing, source, etc.)
+  createdAt?: string;          // ISO timestamp
+  updatedAt?: string;          // ISO timestamp
+}
+```
+
+### Basic Try-Catch Pattern
+
+```typescript
+try {
+  // SUCCESS CASE
+  const job = await client.createJob({
+    name: 'inventory-sync',
+    retailerId: '2'
+  });
+
+  console.log('✅ Job created successfully');
+  console.log('Job ID:', job.id);
+  console.log('Status:', job.status);
+  console.log('Created:', job.createdAt);
+
+} catch (error) {
+  if (error instanceof FluentAPIError) {
+    console.error('❌ Job Creation Error');
+    console.error('Status:', error.statusCode);
+    console.error('Message:', error.message);
+
+    if (error.statusCode === 400) {
+      console.error('   → Invalid job payload');
+    } else if (error.statusCode === 403) {
+      console.error('   → Permission denied');
+    }
+  }
+}
+```
+
+### Job Success Example
+
+**Input:**
+```typescript
+await client.createJob({
+  name: 'product-import-batch',
+  retailerId: '2'
+});
+```
+
+**Output (Success):**
+```json
+{
+  "id": "job-789",
+  "name": "product-import-batch",
+  "status": "CREATED",
+  "retailerId": "2",
+  "createdAt": "2025-01-19T10:30:00Z",
+  "updatedAt": "2025-01-19T10:30:00Z"
+}
+```
+
+---
+
+### Job Status Checking
+
+**Response Structure:**
+```typescript
+interface FluentJobStatus {
+  id: string;
+  status: string;              // Job status (CREATED, ACTIVE, PROCESSING, COMPLETED, FAILED)
+  progress?: number;           // Progress percentage (0-100)
+  message?: string;            // Status message
+  completedAt?: string;         // ISO timestamp when completed
+  failedAt?: string;           // ISO timestamp when failed
+  errors?: Array<{            // Error details (if failed)
+    code: string;
+    message: string;
+  }>;
+}
+```
+
+**Example:**
+```typescript
+try {
+  const status = await client.getJobStatus('job-789');
+
+  console.log('Job Status:', status.status);
+  console.log('Progress:', status.progress);
+
+  if (status.status === 'FAILED') {
+    console.warn('⚠️ Job failed - check errors');
+    console.error('Errors:', status.errors);
+  }
+
+} catch (error) {
+  if (error instanceof FluentAPIError && error.statusCode === 404) {
+    console.error('Job not found');
+  }
+}
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Centralized Error Handler
+
+```typescript
+function handleSDKError(error: unknown, context: string): void {
+  if (error instanceof FluentAPIError) {
+    console.error(`[${context}] API Error:`, {
+      status: error.statusCode,
+      message: error.message,
+      details: error.details
+    });
+
+    // Log to monitoring service
+    logger.error('Fluent API Error', {
+      context,
+      status: error.statusCode,
+      message: error.message
+    });
+
+  } else if (error instanceof GraphQLExecutionError) {
+    console.error(`[${context}] GraphQL Error:`, {
+      message: error.message,
+      errors: error.getErrorMessages(),
+      query: error.query
+    });
+
+    logger.error('GraphQL Execution Error', {
+      context,
+      errors: error.getErrorMessages()
+    });
+
+  } else if (error instanceof AuthenticationError) {
+    console.error(`[${context}] Auth Error:`, {
+      message: error.message,
+      status: error.statusCode
+    });
+
+    // Alert - credentials may be invalid
+    alertService.send('Fluent Auth Failure', error.message);
+
+  } else {
+    console.error(`[${context}] Unexpected Error:`, error);
+    logger.error('Unexpected SDK Error', { context, error });
+  }
+}
+
+// Usage
+try {
+  await client.sendEvent(event);
+} catch (error) {
+  handleSDKError(error, 'Event API');
+  throw error; // Re-throw if needed
+}
+```
+
+---
+
+### Pattern 2: Retry with Backoff
+
+```typescript
+async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  maxRetries: number = 3,
+  baseDelay: number = 1000
+): Promise<T> {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (error instanceof FluentAPIError) {
+        // Only retry 5xx server errors
+        if (error.statusCode >= 500 && attempt < maxRetries) {
+          const delay = baseDelay * Math.pow(2, attempt);
+          console.log(`⚠️ Server error, retrying in ${delay}ms...`);
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+      }
+      throw error;
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+
+// Usage
+const result = await retryWithBackoff(
+  () => client.sendEvent(event),
+  3,
+  1000
+);
+```
+
+---
+
+### Pattern 3: Batch with Dead Letter Queue
+
+```typescript
+interface ProcessingResult {
+  successful: any[];
+  failed: Array<{ item: any; error: string }>;
+}
+
+async function processBatchWithDLQ(
+  items: any[]
+): Promise<ProcessingResult> {
+  const result: ProcessingResult = {
+    successful: [],
+    failed: []
+  };
+
+  for (const item of items) {
+    try {
+      const response = await client.sendEvent({
+        name: 'PRODUCT.UPSERT',
+        entityType: 'PRODUCT',
+        entityRef: item.sku,
+        retailerId: '2',
+        attributes: item
+      });
+
+      result.successful.push(item);
+
+    } catch (error) {
+      if (error instanceof FluentAPIError) {
+        // Add to dead letter queue
+        result.failed.push({
+          item,
+          error: `HTTP ${error.statusCode}: ${error.message}`
+        });
+
+        // Log to DLQ for manual review
+        await deadLetterQueue.add({
+          item,
+          error: error.message,
+          status: error.statusCode,
+          timestamp: new Date().toISOString()
+        });
+      }
+    }
+  }
+
+  return result;
+}
+```
+
+---
+
+## Live Examples
+
+### Test Environment
+
+```yaml
+Base URL: https://api.fluentcommerce.com
+Retailer ID: YOUR_RETAILER_ID
+Client ID: YOUR_CLIENT_ID
+```
+
+### Example 1: Event API Success
+
+**Code:**
+```typescript
+const client = new FluentClient({
+  baseUrl: 'https://api.fluentcommerce.com',
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  username: 'YOUR_USERNAME',
+  password: 'YOUR_PASSWORD',
+  retailerId: 'YOUR_RETAILER_ID'
+});
+
+const result = await client.sendEvent({
+  name: 'OrderCancel1',
+  entityRef: 'G_TEST_FC_POSTMAN_34',
+  entityType: 'ORDER',
+  retailerId: '2'
+}, 'async');
+
+console.log('Success:', result.success);        // true
+console.log('HTTP Status:', result.statusCode); // 200
+```
+
+**Console Output:**
+```
+Success: true
+HTTP Status: 200
+```
+
+---
+
+### Example 2: Event API Error (400)
+
+**Code:**
+```typescript
+try {
+  await client.sendEvent({
+    name: 'InvalidEventName',
+    entityRef: 'TEST-123',
+    entityType: 'ORDER',
+    retailerId: '2'
+  }, 'async');
+} catch (error) {
+  if (error instanceof FluentAPIError) {
+    console.error('Error Status:', error.statusCode);
+    console.error('Error Message:', error.message);
+  }
+}
+```
+
+**Console Output:**
+```
+Error Status: 400
+Error Message: Request failed: 400
+```
+
+---
+
+### Example 3: Sync Mode - No Workflow Match (404)
+
+**Code:**
+```typescript
+try {
+  await client.sendEvent({
+    name: 'OrderCancel1',
+    entityRef: 'SYNC-NO-MATCH',
+    entityType: 'ORDER',
+    retailerId: '2'
+  }, 'sync');
+} catch (error) {
+  if (error instanceof FluentAPIError) {
+    console.error('Sync mode detected workflow failure');
+    console.error('Status:', error.statusCode);  // 404
+  }
+}
+```
+
+**Console Output:**
+```
+Sync mode detected workflow failure
+Status: 404
+```
+
+---
+
+## Summary Table
+
+| API | Success Type | Error Type | SDK Retries | Notes |
+|-----|-------------|------------|-------------|-------|
+| **Event API** | `EventResponse` | `FluentAPIError`, `AuthenticationError` | ✅ 401 (3x), 5xx (3x) | Async = fast, Sync = detects workflow errors |
+| **GraphQL** | `GraphQLResponse` | `GraphQLExecutionError`, `FluentAPIError`, `AuthenticationError` | ✅ 401 (3x), 5xx (3x) | GraphQL errors vs HTTP errors |
+| **Batch API** | `FluentBatchResponse` | `FluentAPIError`, `AuthenticationError` | ✅ 401 (3x), 5xx (3x) | Watch for job expiry (404) |
+| **Job API** | `FluentJobResponse` | `FluentAPIError`, `AuthenticationError` | ✅ 401 (3x), 5xx (3x) | Jobs expire after 1 hour |
+
+---
+
+## Quick Reference
+
+### When to Use Try-Catch
+
+✅ **Always use try-catch** for:
+- `sendEvent()`
+- `graphql()`
+- `sendBatch()`
+- `createJob()`
+- `getJobStatus()`
+- Any SDK method that makes API calls
+
+### Error Handling Checklist
+
+- [ ] Catch `FluentAPIError` for HTTP errors
+- [ ] Catch `AuthenticationError` for auth failures
+- [ ] Catch `GraphQLExecutionError` for GraphQL errors
+- [ ] Check `error.statusCode` to determine error type
+- [ ] Log errors with context for debugging
+- [ ] Implement retry logic for transient errors (5xx)
+- [ ] Use dead letter queue for persistent failures
+- [ ] Alert on authentication failures
+
+---
+
+**SDK Version**: 0.1.46
+**Date**: 2025-01-19