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

sendToolResult Error Handling

getMessages Error Handling

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

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.

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

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