Error Handling

Result Pattern

By default, client.query() returns a Result<QueryOutput>:

type Result<T> =
  | { ok: true; data: T }
  | { ok: false; error: IlanaError };

This avoids uncaught exceptions and makes error handling explicit:

const result = await client.query({ botId: 'bot-123', input: 'Hello' });

if (result.ok) {
  console.log(result.data.response);
} else {
  console.error(result.error.code, result.error.message);
}

throwOnError Mode

If you prefer exceptions, set throwOnError: true in the client config:

const client = new IlanaClient({
  runtimeUrl: 'https://api.getilana.ai',
  token: 'your-token',
  throwOnError: true,
});

try {
  // Returns QueryOutput directly, not wrapped in Result
  const data = await client.query({ botId: 'bot-123', input: 'Hello' });
  console.log(data.response);
} catch (err) {
  if (err instanceof IlanaSDKError) {
    console.error(err.code, err.status, err.message);
  }
}

IlanaError

The error shape returned in Result.error:

interface IlanaError {
  code: IlanaErrorCode;
  message: string;
  status?: number;
  requestId?: string;
  raw?: unknown;
}

Property	Type	Description
`code`	`IlanaErrorCode`	Machine-readable error code
`message`	`string`	Human-readable error description
`status`	`number \| undefined`	HTTP status code from the server
`requestId`	`string \| undefined`	Server request ID for debugging
`raw`	`unknown`	Raw error payload for inspection

IlanaSDKError

Thrown when throwOnError is enabled. Extends Error:

class IlanaSDKError extends Error {
  readonly code: IlanaErrorCode;
  readonly status?: number;
  readonly requestId?: string;
  readonly raw?: unknown;
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing embed token
`FORBIDDEN`	403	Token valid but domain not allowed
`NOT_FOUND`	404	Bot not found
`RATE_LIMITED`	429	Too many requests — try again later
`MESSAGE_CAP_EXCEEDED`	429	Monthly message limit reached for your plan
`INVALID_REQUEST`	400	Malformed request body
`INTERNAL_ERROR`	500	Server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable
`NETWORK_ERROR`	—	Network failure (no response received)
`UNKNOWN_ERROR`	—	Unexpected error

MESSAGE_CAP_EXCEEDED

When the monthly message cap is reached, the error includes additional fields:

{
  code: 'MESSAGE_CAP_EXCEEDED',
  message: 'Monthly message limit exceeded',
  status: 429,
  raw: {
    tier: 'free',
    limit: 100,
    resetAt: '2026-03-01T00:00:00.000Z'
  }
}