Errors

The ErrorInfo type that every AI Transport failure path surfaces, the numeric codes you match against, and the patterns for handling errors on the client and the agent.

Every failure surfaces as an ErrorInfo object. The same type covers AI Transport-specific failures, Ably platform errors (auth, channel attach, rate limits), and underlying network errors. Match against a specific code with the errorInfoIs utility.

ErrorInfo

The ErrorInfo type is exported from ably. AI Transport surfaces it as the rejection reason on every promise that can fail, and as the argument to every on('error') listener.

Properties

codeNumber

Ably error code. Match against this with errorInfoIs to identify a specific failure.

messageString

Human-readable description of the error.

statusCodeNumber

HTTP-equivalent status code for the error.

causeErrorInfo or Undefined

The underlying cause of the error, when applicable.

detailRecord<string, string> or Undefined

Structured metadata associated with the error.

AI Transport error codes

General errors

Code	Name	HTTP status	Description	Recovery
40000	BadRequest	400	The request was malformed or missing required fields.	Check the request payload and ensure all required fields are present.
40003	InvalidArgument	400	An argument passed to a session or run method was invalid.	Verify the arguments match the expected types and constraints.
40033	OperationCancelled	400	The operation was cancelled. The run was cancelled, the caller's abort signal fired, or the session began closing while the operation was in flight.	Expected during a deliberate cancel. Treat it as a normal outcome rather than a failure to retry.
40160	InsufficientCapability	401	The Ably channel rejected a publish for a capability reason. The token does not permit the operation.	Add the missing capability to the token.
50000	InternalError	500	An internal invariant failed, so the SDK cannot explain or recover from what it observed.	Retry the operation.

Session and run errors

Code	Name	HTTP status	Description	Recovery
104000	EncoderRecoveryFailed	500	The encoder failed to recover after a publish error. One or more `updateMessage` calls could not recover a failed append pipeline.	Non-fatal. The message may be incomplete on the channel, so check connectivity and decide whether to republish. The run itself is unaffected.
104001	SessionSubscriptionError	500	The session's channel subscription failed. Either the subscribe and attach step failed, or a session-level subscription callback threw while processing an inbound message.	Check the subscription callback for unhandled exceptions. Inspect the underlying error for details.
104002	CancelListenerError	500	A run-scoped callback threw while the SDK invoked it: the `onCancel` hook processing a cancel message, or the `onSteer` hook notifying that a steering message folded into the run.	Check the hook for unhandled exceptions. The run may not respond to subsequent cancels.
104003	RunLifecycleError	500	A publish within a run failed (lifecycle event, message, or codec event).	Check channel permissions and connection state. Surface the error to the calling HTTP handler so the client's pending send fails.
104004	SessionClosed	400	An operation was attempted on a session, view, or encoder that has already been closed.	Create a new session. Do not reuse a closed session.
104005	SessionSendFailed	500	A send failed: either the core's channel publish failed, or the Vercel chat transport's agent-invocation POST failed (network error or non-2xx response).	Check the API endpoint URL, network connectivity, and authentication. Inspect the underlying error for details.
104006	ChannelContinuityLost	500	The Ably channel lost message continuity. The channel entered `FAILED`, `SUSPENDED`, or `DETACHED`, or re-attached with `resumed: false`. Active streams can no longer be guaranteed to receive all events.	Surfaced via the session's `on('error')` on both the client and the agent. End active runs; subsequent operations can resume once the channel reattaches.
104007	ChannelNotReady	400	An operation was attempted but the channel is not in a usable state (not `ATTACHED` or `ATTACHING`).	Wait for the channel to attach before retrying, or inspect channel state and connection state for the underlying cause.
104008	StreamError	500	An error occurred while piping a response stream to the session. Either the source event stream threw (LLM provider rate limit, model error, network failure) or an underlying publish failed mid-stream.	Inspect `cause` for the provider error. End the run with reason `'error'`. The error is also returned on `StreamResult.error` from `Run.pipe`.
104010	InputEventNotFound	504	A fresh process adopting an open run with `load()` waited for that run's `ai-run-start` across the live subscription and a bounded history scan, and the `timeoutMs` bound lapsed without seeing it. Any history-fetch failure is preserved as `cause`.	Retryable. It usually means a workflow ordering problem where the open activity's run-start has not propagated yet. Retry with a longer `timeoutMs`.
104011	HistoryFetchFailed	500	Channel history pagination failed after bounded retry. Either the initial `channel.history()` call or a later `page.next()` exhausted its retry budget. Also used when a history load fails with an error that is not already an `ErrorInfo`.	Inspect `cause`. Retry the load, and check channel permissions if it persists. Surfaced on `useView`'s `loadError`.

Auth and channel errors

Auth and channel errors come from the Ably platform, not AI Transport. The most common codes you encounter:

Code	Description	Recovery
40142	Token expired.	Refresh the token (handled automatically with `authUrl`/`authCallback`).
40300	Forbidden.	The token is valid but not authorised for this resource.
80000	Channel attach failed.	Check the channel name and capability.
90000	Internal channel error.	Retry the operation. If the error persists, contact support.
93002	`Can only update/delete/append messages on channels with mutableMessages enabled`. The namespace lacks the `mutableMessages` rule, so AI Transport cannot append stream tokens. This is the most common AI Transport setup failure.	Enable the Message annotations, updates, deletes, and appends rule on the namespace.

The Ably error codes page lists every code the platform returns.

Match an ErrorInfo against a code

errorInfoIs(errorInfo: Ably.ErrorInfo, error: ErrorCode): boolean

errorInfoIs returns true if the ErrorInfo's code matches the supplied ErrorCode. Use it in error handlers to branch on specific failures without writing string comparisons against the message.

JavaScript

import { errorInfoIs, ErrorCode } from '@ably/ai-transport';

session.on('error', (error) => {
  if (errorInfoIs(error, ErrorCode.SessionClosed)) {
    reconnect();
  }
});

Example

Handle session-level and run-level errors separately. Both the client and the agent subscribe to session errors with session.on('error'). The agent additionally uses the run runtime's onError for per-run failures.

JavaScript

import { errorInfoIs, ErrorCode } from '@ably/ai-transport';

// Client side: subscribe to session-level errors.
session.on('error', (error) => {
  console.error(`Error ${error.code}: ${error.message}`);
  if (errorInfoIs(error, ErrorCode.ChannelContinuityLost)) {
    showReconnectBanner();
  }
});

// Agent side: handle session and run-level errors separately.
const agentSession = createAgentSession({ client: ably, channelName, codec });

await agentSession.connect();

agentSession.on('error', (error) => {
  console.error('Session error:', error);
});

const run = agentSession.createRun(invocation, {}, {
  signal: req.signal,
  onError(error) {
    console.error('Run error:', error);
  },
});

// End a run with reason 'error' when piping fails.
try {
  const result = await run.pipe(llmStream);
  await run.end({ reason: result.reason });
} catch (error) {
  await run.end({ reason: 'error' });
}

To give clients specific detail, optionally pass an Ably.ErrorInfo: run.end({ reason: 'error', error: new Ably.ErrorInfo(message, code, statusCode) }). Omit error to end in error without detail and the client sees a generic fallback; either way clients read it from RunInfo.error and the session error event.