Errors

Package: @pai/client

Thread Error Classes

class ThreadBusyError extends Error {
  readonly threadId: ThreadId;
  readonly threadStatus: ThreadStatus;
  readonly activeRunId?: RunId;
}

class ThreadNotFoundError extends Error {
  readonly code: "thread_not_found";
  readonly threadId: ThreadId;
}

class ThreadConflictError extends Error {
  readonly code: "thread_conflict";
  readonly threadId: ThreadId;
}

class ThreadAgentMismatchError extends Error {
  readonly code: "thread_agent_mismatch";
  readonly threadId: ThreadId;
  readonly threadAgent: string;
  readonly runtimeAgent: string;
}

class ThreadDirectExecutionError extends Error {
  readonly code: "thread_direct_execution";
  readonly threadId: ThreadId;
}

class InvalidPageTokenError extends Error {
  readonly code: "invalid_page_token";
}

class ThreadRetryUnavailableError extends Error {
  readonly threadId: ThreadId;
}

ThreadBusyError means a send, trigger, or regenerate could not start because the thread is already busy. Wait until it is idle, or stop the active run, then try again. ThreadConflictError covers durable state conflicts. ThreadAgentMismatchError and ThreadDirectExecutionError are execution authority failures. InvalidPageTokenError identifies a malformed or query-mismatched continuation token. ThreadRetryUnavailableError is local to the high-level thread.retry() convenience.

The HTTP transport rehydrates the same classes from structured receiver responses. Other HTTP response and established-stream failures use PaiHttpError from @pai/client-http. Network and response-decoding failures use its "response" phase, while established-stream read and decode failures use "stream". Caller abort reasons remain unchanged.

Background Run Errors

An admitted run can fail after its initiating request succeeds. ThreadState.error exposes the safe persisted ThreadErrorRecord:

const state = await (await thread.send("Draft")).waitUntilIdle();

if (state.error) {
  console.log(state.error.code);
  console.log(state.error.message);
  console.log(state.error.errorId);
  console.log(state.error.retryable);
}

The original exception is not part of client state. The optional errorId correlates this safe record with a trusted server diagnostic.

See Errors for mapping, reporting, rendering, and privacy guidance.