Error Handling

Error handling patterns, try/catch blocks, and error types in the III SDK

Overview

The III SDK provides structured error handling across function invocations, WebSocket connections, and trigger registrations. Understanding error types and handling patterns ensures robust distributed applications.

Error Types

Invocation Errors

When calling remote functions, the SDK returns structured error objects:

Node.js

// Error structure from InvocationResultMessage
type InvocationError = {
  code: 'invocation_failed' | 'function_not_found'
  message: string
}

// Timeout error
try {
  await iii.call('my-function', { data: 'value' }, 5000)
} catch (error) {
  // Error: Invocation timeout after 5000ms: my-function
  console.error(error.message)
}

Registration Errors

Node.js

// Duplicate function ID
try {
  iii.registerFunction({ id: 'users::get' }, handler)
  iii.registerFunction({ id: 'users::get' }, handler) // throws
} catch (error) {
  // Error: function id already registered: users::get
}

// Missing required fields
try {
  iii.registerFunction({ id: '' }, handler)
} catch (error) {
  // Error: id is required
}

Trigger Registration Errors

Node.js

// Trigger handler errors are communicated via TriggerRegistrationResult
iii.registerTriggerType(
  { id: 'cron', description: 'Cron trigger' },
  {
    registerTrigger: async (config) => {
      if (!config.config.schedule) {
        throw new Error('schedule is required')
      }
      // Error propagated to engine as:
      // { code: 'trigger_registration_failed', message: 'schedule is required' }
    },
    unregisterTrigger: async (config) => {},
  }
)

Function Handler Error Handling

Try/Catch in Handlers

1. Wrap handler logic in try/catch

   Catch errors inside your function handlers to return meaningful responses:

   Node.js

   import { getContext } from 'iii-sdk'
   
   iii.registerFunction({ id: 'users::create' }, async (input) => {
     const { logger } = getContext()
     
     try {
       // Validate input
       if (!input.email) {
         logger.warn('Missing email field', { input })
         return { error: 'email is required' }
       }
       
       // Perform operation
       const user = await db.createUser(input)
       logger.info('User created', { userId: user.id })
       return { success: true, user }
       
     } catch (error) {
       logger.error('Failed to create user', { error: error.message, input })
       
       // Return structured error response
       if (error.code === 'DUPLICATE_KEY') {
         return { error: 'User already exists' }
       }
       
       return { error: 'Internal server error' }
     }
   })
   
2. Log errors with context

   Use the context logger to attach trace IDs and span IDs automatically:

   Node.js

   iii.registerFunction({ id: 'process::payment' }, async (input) => {
     const { logger, trace } = getContext()
     
     try {
       const result = await stripe.charge(input.amount)
       return result
     } catch (error) {
       // Automatically includes trace_id, span_id, function_id
       logger.error('Payment failed', { 
         amount: input.amount,
         stripeError: error.code 
       })
       
       // Add error details to span
       trace?.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
       trace?.recordException(error)
       
       throw error // Re-throw to return error to caller
     }
   })
   

Uncaught Errors

If a handler throws an uncaught error, the SDK automatically catches it and returns an error response to the caller:

Node.js

iii.registerFunction({ id: 'divide' }, async ({ a, b }) => {
  return a / b // Will throw if not numbers
})

// Caller receives:
// {
//   error: {
//     code: 'invocation_failed',
//     message: 'Cannot read property of undefined'
//   }
// }

Invocation Error Handling

Configuring Timeouts

Node.js

import { init, DEFAULT_INVOCATION_TIMEOUT_MS } from 'iii-sdk'

// Set default timeout for all invocations
const iii = init('ws://localhost:49134', {
  invocationTimeoutMs: 10000 // 10 seconds
})

// Override per-invocation
try {
  const result = await iii.call('slow-function', data, 30000) // 30 seconds
} catch (error) {
  if (error.message.includes('timeout')) {
    console.error('Function took too long')
  }
}

Handling Connection Errors

Node.js

import type { ConnectionStateCallback } from 'iii-sdk'

const handleConnectionState: ConnectionStateCallback = (state) => {
  switch (state) {
    case 'connected':
      console.log('Ready to invoke functions')
      break
    case 'reconnecting':
      console.warn('Connection lost, retrying...')
      break
    case 'failed':
      console.error('Max retries reached, connection failed')
      // Implement fallback or alert
      break
  }
}

iii.onConnectionStateChange(handleConnectionState)

Best Practices

Error Handling Checklist:

• ✅ Always validate input at the start of handlers
• ✅ Use structured error responses (not just strings)
• ✅ Log errors with context using ctx.logger.error()
• ✅ Set appropriate timeouts for long-running operations
• ✅ Handle connection state changes for resilience
• ✅ Record exceptions in spans for distributed tracing
• ✅ Differentiate between client errors (4xx) and server errors (5xx)

Graceful Degradation

Node.js

iii.registerFunction({ id: 'get-recommendations' }, async (input) => {
  const { logger } = getContext()
  
  try {
    // Try ML service first
    return await iii.call('ml::recommend', input, 5000)
  } catch (error) {
    logger.warn('ML service unavailable, using fallback', { error: error.message })
    
    // Fallback to simple logic
    return await iii.call('db::popular-items', { limit: 10 })
  }
})

Shutdown Error Handling

Node.js

// Graceful shutdown rejects pending invocations
process.on('SIGTERM', async () => {
  console.log('Shutting down...')
  await iii.shutdown() // Rejects all pending with 'iii is shutting down'
  process.exit(0)
})