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

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

<Table id='ErrorInfoProperties'>

| Property | Description | Type |
| --- | --- | --- |
| code | Ably error code. Match against this with `errorInfoIs` to identify a specific failure. | Number |
| message | Human-readable description of the error. | String |
| statusCode | HTTP-equivalent status code for the error. | Number |
| cause | The underlying cause of the error, when applicable. | `ErrorInfo` or Undefined |
| detail | Structured metadata associated with the error. | `Record<string, string>` or Undefined |

</Table>

## 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](https://ably.com/docs/ai-transport/concepts/authentication.md). |
| 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](https://ably.com/docs/sdks/error-codes.md).

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

<Code>

### Javascript

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

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

## Example

<Code>

### 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');
}
```
</Code>

## Related Topics

- [Overview](https://ably.com/docs/ai-transport/api.md): API reference for Ably AI Transport. Client transport, server transport, React hooks, Vercel integration, codec, and errors.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.