Errors

@pai/client exports the thread errors that application code can handle portably across direct and HTTP transports. The HTTP transport rehydrates these classes from structured error responses, so consumers do not need to branch on status codes or parse error messages.

Typed Thread Errors

import {
  ThreadBusyError,
  ThreadConflictError,
} from "@pai/client";

try {
  await thread.send("Continue");
} catch (error) {
  if (error instanceof ThreadBusyError) {
    await thread.send("Continue", { queue: { mode: "queue" } });
  } else if (error instanceof ThreadConflictError) {
    await thread.refresh();
  } else {
    throw error;
  }
}

The exported classes are:

• ThreadBusyError — a send could not start immediately and no accepting queue policy was supplied. It exposes threadId, threadStatus, and optional activeRunId.
• ThreadNotFoundError — the requested persisted thread does not exist.
• ThreadConflictError — the operation conflicts with the current durable thread state.
• ThreadAgentMismatchError — execution was requested through a runtime for a different owning agent.
• ThreadDirectExecutionError — direct execution was requested for a delegated-only thread.
• InvalidPageTokenError — an opaque pagination token is malformed or belongs to another query.
• ThreadRetryUnavailableError — thread.retry() found no failed user message that can be regenerated.

The high-level client treats an unrealized thread as an empty local handle, so thread.refresh() returns an empty default thread state instead of throwing ThreadNotFoundError. Lower-level transport and trusted runtime operations can still surface the not-found class.

@pai/client-http uses PaiHttpError for other non-success responses and transport failures. Network and response-decoding failures use phase: "response"; failures after an SSE response is established use phase: "stream". PAI-authored, versioned error DTOs preserve safe status, code, retry, and diagnostic-reference fields without exposing the server exception. Other transport details are replaced with a generic safe message. Caller abort reasons and portable typed domain errors remain unchanged.

Background failures after a run has been admitted appear in ThreadState.error, including an optional support reference that survives refresh and watch reconnects.

See Error Handling for the complete client/server workflow and Client Errors for rendering each client error path.

Retry-Safe Inputs

const messageId = crypto.randomUUID();

await thread.send("Create the report", { messageId });

PAI does not expose generic command receipts. For operations where retries matter, use caller-chosen ids on the resource being created, such as threadId for a thread handle or messageId in send and trusted trigger flows.