TypeScript API: Errors

Every error class, one per stable error code. Generated from the declarations and doc comments of criogenai 0.1.7. See also: TypeScript API overview, the same module in Python.

import {
  CriogenError,
  NativeUnavailableError,
  ModelError,
  ToolExecutionError,
  LimitExceededError,
  ThreadBusyError,
  ThreadSuspendedError,
  StorageError,
  ValidationError,
  CancelledError,
  isCriogenError,
} from "criogenai";

Contents#

CriogenError#

class CriogenError extends Error {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

Any CriogenAI failure. code is stable across languages.

Every error the engine raises is a CriogenError or one of its subclasses, chosen by code. The message starts with the code ("limit_exceeded: ..."). Branch on the class or on code, never on the message text.

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

Example

import { Agent, FakeModel, FakeReply, LimitExceededError, tool } from "criogenai";

const ping = tool({ name: "ping", description: "Ping.", input: { type: "object" }, run: () => "pong" });
const agent = new Agent({ model: new FakeModel([FakeReply.toolCall("ping")]), tools: [ping], limits: { modelCalls: 1 } });
try {
  await agent.run("Keep pinging.");
} catch (error) {
  if (error instanceof LimitExceededError) console.log(error.code, error.details); // limit_exceeded { limit: "model_calls", value: 1 }
  else throw error;
}

CriogenError.code#

readonly code: string

The stable snake_case error code, e.g. "model_failed" (listed in the errors reference).

CriogenError.details#

readonly details: Record<string, unknown>

Structured facts about the failure (which limit, which call, ...); {} when there are none.

NativeUnavailableError#

class NativeUnavailableError extends CriogenError {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

The native engine cannot be loaded on this system (native_unavailable). Thrown on first use, never at import: details names the platform, the architecture, the C library and the package that was tried.

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

ModelError#

class ModelError extends CriogenError {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

The model failed after retries (model_failed).

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

ToolExecutionError#

class ToolExecutionError extends CriogenError {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

A tool crashed (tool_failed); cause is the thrown value.

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

LimitExceededError#

class LimitExceededError extends CriogenError {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

A run limit was reached (limit_exceeded).

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

ThreadBusyError#

class ThreadBusyError extends CriogenError {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

Another run holds the thread (thread_busy).

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

ThreadSuspendedError#

class ThreadSuspendedError extends CriogenError {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

The thread waits for approval (thread_suspended).

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

StorageError#

class StorageError extends CriogenError {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

Storage failed (storage_*, encryption_*, audit_failed).

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

ValidationError#

class ValidationError extends CriogenError {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

Something given was not accepted (invalid_*, resume_invalid).

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

CancelledError#

class CancelledError extends CriogenError {
  constructor(code: string, message: string, details?: Record<string, unknown> | null, cause?: unknown);
}

The run was cancelled (cancelled), e.g. by an AbortSignal.

Parameters

• code (string): The stable error code.
• message (string): What went wrong; the error's message is "<code>: <message>".
• details (Record<string, unknown> | null, optional): Structured facts about the failure.
• cause (unknown, optional): What caused it, e.g. the value a crashing tool threw; becomes the error's cause.

isCriogenError#

function isCriogenError(error: unknown, code?: string): boolean

true if error is a CriogenAI error, with code if given.

Parameters

• error (unknown): Any caught value.
• code (string, optional): Also require this error code, e.g. "thread_busy".

Example

import { isCriogenError } from "criogenai";

try {
  await thread.send("Hello");
} catch (error) {
  if (isCriogenError(error, "thread_busy")) console.log("Try again in a moment.");
  else throw error;
}