Skip to main content
The SDK uses both thrown errors and structured results depending on the API.

​
Handling ILLA SDK errors

When using the IllaSDK class, errors are returned as structured results.

​
sendMessage Error Handling

import { IllaSDK } from '@illalabs/sdk'

const sdk = new IllaSDK({
  apiKey: process.env.ILLA_API_KEY!
})

const result = await sdk.sendMessage(
  'Swap 1 ETH for USDC',
  { userContext: { address: '0x1234...' } }
)

if (!result.response.isError) {
  // Success: access the response data
  console.log('Text:', result.response.data.text)
  console.log('Messages:', result.messages)

  // Check for pending tools
  if (result.response.data.pendingTools) {
    console.log('Tools to execute:', result.response.data.pendingTools)
  }
} else {
  // Error: inspect the error object
  console.error('Error occurred:', result.response.error)
}

​
sendToolResult Error Handling

try {
  const result = await sdk.sendToolResult(chatId, toolResult)

  if (!result.response.isError) {
    console.log('Success:', result.response.data.text)
  } else {
    console.error('Error:', result.response.error)
  }
} catch (error) {
  // Thrown when chatId doesn't exist
  if (error instanceof ChatNotFound) {
    console.error('Chat not found:', error.chatId)
  }
}

​
getMessages Error Handling

import { ChatNotFound } from '@illalabs/sdk'

try {
  const messages = await sdk.getMessages(chatId)
  console.log('Messages:', messages)
} catch (error) {
  if (error instanceof ChatNotFound) {
    console.error('Chat not found:', error.chatId)
  }
}

​
Advanced: Lower-Level Component Errors

​
Thrown errors (public)

  • PromptConfigurationConflict: Creating Prompt with both or neither text/toolResult
  • CoreApiAuthenticationMissing: Constructing CoreApiProvider without x-api-key
  • CoreApiMethodNotImplemented: Server returned HTTP 501 to a provider call
import { CoreApiProvider, Prompt } from '@illalabs/sdk'

try {
  new Prompt({
    text: 'hi',
  })
} catch (e) {
  // handle misconfiguration
}

try {
  new CoreApiProvider({ headers: {} as any })
} catch (e) {
  // missing auth
}

​
Structured results

  • chat.sendMessage(prompt) returns an object with status and either response or error
  • AsyncToolChecker.check(...) returns a discriminated union { isError: boolean, response?: ..., error?: ... }
Always inspect the shape before using the payload. 
const res = await chat.sendMessage(prompt)
if (!res.response.isError) {
  // success: access response text and messages
  console.log('Text:', res.response.data.text)
  console.log('Messages:', res.messages)
  // Check for pending tools
  if (res.response.data.pendingTools) {
    console.log('Pending tools:', res.response.data.pendingTools)
  }
} else {
  // error: inspect error fields
  console.error('Error:', res.response.error)
}

​
Long-running actions

  • Chat.awaitAction(...) throws ChatAsyncToolCheckerUnavailable if no AsyncToolChecker is configured (note: this error class is not exported)
  • AsyncToolChecker.subscribe(...) delivers issues via onError callback (e.g., timeouts, max retries) rather than throwing
const sub = asyncToolChecker.subscribe(
  {
    /* ... */
  },
  {
    onStatusChange: (ev) => console.log(ev),
    onError: (err) => console.error('Polling failed', err),
  }
)

// later
sub.unsubscribe()

​
Error Handling Best Practices

  • Wrap SDK calls in try/catch when constructing objects or when a method documents it may throw
  • Prefer discriminated unions and status codes for flow control over exceptions from network errors
  • Log unexpected error shapes for observability