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 server.

Open in

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 transport method was invalid.	Verify the arguments match the expected types and constraints.

Transport errors

Code	Name	HTTP status	Description	Recovery
104000	EncoderRecoveryFailed	500	The encoder failed to recover after a publish error. The turn cannot continue.	End the turn with reason `'error'` and start a new one. The client sees the partial response up to the failure point.
104001	TransportSubscriptionError	500	A channel subscription callback threw unexpectedly.	Check the subscription callback for unhandled exceptions. Inspect the underlying error for details.
104002	CancelListenerError	500	The transport failed to register or process a cancel listener.	The turn does not respond to cancel signals. End the turn manually if needed.
104003	TurnLifecycleError	500	A turn lifecycle event failed to publish.	Check channel permissions and connection state. The turn-start or turn-end message could not be published.
104004	TransportClosed	400	An operation was attempted on a transport that has been closed.	Create a new transport instance. Do not reuse a closed transport.
104005	TransportSendFailed	500	The client transport failed to send a message to the API endpoint.	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 cannot be guaranteed to receive all events.	Surfaced via the transport's `on('error')` and the server transport's `onError` option. Active turns should be ended; subsequent operations can resume once the channel reattaches.
104007	ChannelNotReady	500	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 channel. 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 turn with reason `'error'`.

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`).
40160	Token capability does not permit the operation.	Add the missing capability to the token. See authentication.
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.

The full Ably error code list lives at Ably error codes.

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';

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

Example

JavaScript

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

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

// Server-side: handle transport and turn-level errors separately.
const serverTransport = createServerTransport({
  channel,
  codec,
  onError(error) {
    console.error('Transport error:', error);
  },
});

const turn = serverTransport.newTurn({
  turnId,
  onError(error) {
    console.error('Turn error:', error);
  },
});

// End a turn with reason 'error' when streaming fails.
try {
  const { reason } = await turn.streamResponse(llmStream);
  await turn.end(reason);
} catch (error) {
  await turn.end('error');
}