Python API: Errors

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

Errors: one exception class per family of failures.

Every exception carries the stable code the Rust engine uses (for example model_failed or thread_busy), the same in every language; the error reference (/docs/reference/errors/) lists them all. Catch a class for a family, or compare error.code for one failure.

from criogenai import (
    CriogenError,
    ModelError,
    ToolExecutionError,
    LimitExceededError,
    ThreadBusyError,
    ThreadSuspendedError,
    StorageError,
    ValidationError,
    CancelledError,
)

Contents#

CriogenError#

class CriogenError(Exception):
    def __init__(self, code: str, message: str, details: Optional[Dict[str, Any]] = None)

Any CriogenAI failure; the base class of the others.

The engine raises these; you rarely build one yourself. str(error) is "<code>: <message>".

Parameters

• code (str): The stable snake_case error code, such as "model_failed".
• message (str): What went wrong, for people.
• details (Optional[Dict[str, Any]], default None): More about the failure as a JSON-like dict (it may hold the run's snapshot). Default {}.

Example

from criogenai import CriogenError, LimitExceededError

try:
    result = agent.run_sync("Plan the week.")
except LimitExceededError:
    print("the run hit a limit")
except CriogenError as error:
    print(error.code, error.message)

CriogenError.snapshot#

snapshot: Optional[Dict[str, Any]]

The run's snapshot, if the error carries one.

ModelError#

class ModelError(CriogenError)

The model failed after retries (model_failed).

ToolExecutionError#

class ToolExecutionError(CriogenError)

A tool crashed (tool_failed); __cause__ is the exception.

LimitExceededError#

class LimitExceededError(CriogenError)

A run limit was reached (limit_exceeded).

ThreadBusyError#

class ThreadBusyError(CriogenError)

Another run holds the thread (thread_busy).

ThreadSuspendedError#

class ThreadSuspendedError(CriogenError)

The thread waits for approval (thread_suspended).

StorageError#

class StorageError(CriogenError)

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

ValidationError#

class ValidationError(CriogenError)

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

CancelledError#

class CancelledError(CriogenError)

The run was cancelled (cancelled).