> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Understand runtime errors and SDK responses

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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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.

```ts theme={null}
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

```ts theme={null}
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