Error codes | CriogenAI

Every failure has a stable code, the same in Python, TypeScript, Rust and the gateway, so code that checks codes works everywhere. Codes may be added; before 1.0 none is renamed or removed.

from criogenai import CriogenError, ThreadBusyError

try:
    await chat.send("Hello")
except ThreadBusyError:
    ...                      # another run holds the thread
except CriogenError as error:
    print(error.code, error.message, error.details)

import { isCriogenError } from "criogenai";

try {
  await chat.send("Hello");
} catch (error) {
  if (isCriogenError(error, "thread_busy")) { /* … */ }
}

In Rust, RunError::kind.code(), AgentError::code, StorageError::code() and ModelErrorKind::code() give the same strings.

Run errors#

Code	Meaning	Retry?	SDK class
`node_failed`	A workflow node returned an error.	no	`CriogenError`
`node_panicked`	A Rust node panicked; the run failed instead of the process.	no	`CriogenError`
`node_timeout`	A node attempt took longer than its policy timeout.	yes	`CriogenError`
`router_failed`	A router function returned an error.	no	`CriogenError`
`unknown_route`	A router returned a label with no edge.	no	`CriogenError`
`missing_goto`	A node that must choose the next node did not.	no	`CriogenError`
`memo_type_mismatch`	A saved task memo entry does not have the shape the node asks for (or a value to save is not JSON); seen as the kind of a node_failed error.	no	`CriogenError`
`update_conflict`	Two nodes wrote the same state key in one step without a reducer.	no	`CriogenError`
`step_limit_exceeded`	The run reached its step limit.	no	`LimitExceededError`
`deadline_exceeded`	The run reached its deadline, or the next retry would pass it.	no	`LimitExceededError`
`cancelled`	The run was cancelled (a cancel token, an AbortSignal, a dropped stream, an interrupt from another process). In a tool message: a call that never got a result.	yes	`CancelledError`
`invalid_value`	A value was not accepted: a state write a reducer cannot apply, a memory key, value, namespace or vector, a configuration value.	no	`ValidationError`
`resume_invalid`	A resume or approval decision does not match what the run waits for.	no	`ValidationError`
`workflow_mismatch`	A snapshot was made by a different workflow.	no	`ValidationError`
`storage_failed`	Saving the run's progress failed; details carry the storage code.	yes	`StorageError`
`model_failed`	A model call failed after retries and fallbacks; details.model_error has the kind, and retryable follows it.	depends	`ModelError`
`tool_failed`	A tool failed with an error it did not handle (an exception, a panic). By default the model sees it as the call's result and the run goes on; with on_tool_exception="fail" (or ToolError::fatal) it fails the run.	no	`ToolExecutionError`
`limit_exceeded`	A model-call, tool-call, token or nesting limit was reached; details.limit names it.	no	`LimitExceededError`
`output_invalid`	The structured output was still invalid after the allowed retries.	no	`CriogenError`
`hook_failed`	A hook returned an error.	no	`CriogenError`
`invalid_state`	The run state is not an agent's, or memory cannot find the run's namespace.	no	`ValidationError`
`invalid_input`	The input names one of the agent's own state keys, or tries to change the value that scopes the thread's memory.	no	`ValidationError`
`audit_failed`	An audit record could not be written, so the action it describes failed.	yes	`StorageError`

Thread errors#

Code	Meaning	Retry?	SDK class
`thread_busy`	Another run holds the thread (OnBusy reject, or the wait timed out).	yes	`ThreadBusyError`
`thread_suspended`	The thread waits for approval: answer it before sending more.	no	`ThreadSuspendedError`
`thread_interrupted`	The thread's last run did not finish: continue it with retry.	no	`CriogenError`

Storage errors#

Code	Meaning	Retry?	SDK class
`invalid_value`	A value was not accepted: a state write a reducer cannot apply, a memory key, value, namespace or vector, a configuration value.	no	`ValidationError`
`audit_failed`	An audit record could not be written, so the action it describes failed.	yes	`StorageError`
`thread_busy`	Another run holds the thread (OnBusy reject, or the wait timed out).	yes	`ThreadBusyError`
`storage_unavailable`	The database could not be reached or timed out.	yes	`StorageError`
`storage_conflict`	Another writer changed the thread first.	yes	`StorageError`
`checkpoint_not_found`	No checkpoint with that id.	no	`StorageError`
`storage_corrupt`	Stored data could not be read.	no	`StorageError`
`storage_incompatible`	The database was written by a newer schema version.	no	`StorageError`
`encryption_key_missing`	Encrypted data, or an encrypted database, without the key to read it.	no	`StorageError`
`encryption_key_invalid`	A key does not match the one the database knows under its id.	no	`StorageError`

Model errors (inside model_failed)#

Code	Meaning	Retry?	SDK class	HTTP
`rate_limited`	The provider asked us to slow down.	yes	–	429
`overloaded`	The provider is overloaded.	yes	–	503
`server`	The provider failed (5xx).	yes	–	502
`timeout`	No answer in time: a model call, or (in a tool message) a tool call.	yes	–	504
`network`	The connection failed or broke.	yes	–	502
`auth`	The provider refused the API key.	no	–	502
`permission`	The key may not use this model or feature.	no	–	502
`not_found`	The provider does not know the model or endpoint.	no	–	502
`invalid_request`	The provider (or the gateway) rejected the request as malformed.	no	–	400
`context_overflow`	The conversation is longer than the model's context.	no	–	400
`content_filter`	The provider's safety system refused the request.	no	–	400
`quota_exhausted`	Billing or quota is exhausted; another provider may still answer.	no	–	502
`invalid_response`	A successful response whose body could not be read (already billed, so not retried).	no	–	502
`unknown`	An unclassified provider failure.	no	–	502

Tool results (the model sees these; the run goes on)#

Code	Meaning	Retry?	SDK class
`cancelled`	The run was cancelled (a cancel token, an AbortSignal, a dropped stream, an interrupt from another process). In a tool message: a call that never got a result.	yes	`CancelledError`
`tool_failed`	A tool failed with an error it did not handle (an exception, a panic). By default the model sees it as the call's result and the run goes on; with on_tool_exception="fail" (or ToolError::fatal) it fails the run.	no	`ToolExecutionError`
`timeout`	No answer in time: a model call, or (in a tool message) a tool call.	yes	–
`invalid_arguments`	The model's arguments did not match the tool's schema; the model sees the problems and may correct them.	no	–
`unknown_tool`	The model called a tool the agent does not have.	no	–
`tool_error`	The tool reported a failure meant for the model (ToolError).	no	–

Build errors#

Code	Meaning	Retry?	SDK class
`invalid_agent`	An SDK agent configuration the engine could not build.	no	`ValidationError`
`invalid_workflow`	An SDK workflow that does not validate (`details.issues` lists the problems).	no	`ValidationError`
`unsupported`	The feature needs a server, and here the engine runs as WebAssembly in a JavaScript host (the browser, design 0021): databases (SQLite, Postgres), encryption at rest, telemetry export, web tools.	no	`CriogenError`
`mcp_connect`	An MCP server could not be started or reached, or refused the credentials (design 0022).	no	`CriogenError`
`mcp_protocol`	An MCP server answered something the client cannot use: a malformed message, an error, or a protocol version CriogenAI does not speak.	no	`CriogenError`
`mcp_tool_name`	Two of an MCP server's tools map to the same name, or a name maps to nothing: set a prefix or leave one out with `except`.	no	`CriogenError`
`mcp_tool_schema`	An MCP tool's input schema is not an object schema, or is too large or too deep: leave the tool out with `except`.	no	`CriogenError`
`mcp_timeout`	An MCP server was not ready within the connect timeout.	yes	`CriogenError`
`mcp_closed`	The MCP server stopped (its process exited) or the client was closed.	no	`CriogenError`
`eval_failed`	An eval missed a bar set by `check` (design 0024): a pass rate, a scorer's mean, or a regression against the baseline; `details.failures` lists them.	no	`CriogenError`

Gateway errors (HTTP)#

Code	Meaning	Retry?	SDK class	HTTP
`invalid_request`	The provider (or the gateway) rejected the request as malformed.	no	–	400
`invalid_api_key`	The gateway needs a valid virtual key.	no	–	401
`model_not_found`	No route by that name, or the key may not use it.	no	–	404
`key_rate_limited`	The key's requests or tokens per minute are used up; Retry-After says when to try again.	yes	–	429
`concurrency_limited`	Too many requests are in flight, over the gateway or for this key; Retry-After says when to retry.	yes	–	429
`budget_exceeded`	The key's token budget is spent for the current day or month (Retry-After: until it ends), or in total.	no	–	429