errors: Add AI Transport (AIT) error codes 104000-104011 - #353
Conversation
Add the AI Transport SDK's own error codes to the registry, from the AIT errors docs page plus the two codes defined in ably-ai-transport-js that the page omits (104010, 104011). - 104000 streamed_message_finalize_failed - 104001 session_subscription_failed - 104002 run_cancel_handler_failed - 104003 run_lifecycle_publish_failed - 104004 session_closed - 104005 session_send_failed - 104006 session_continuity_not_guaranteed - 104007 session_channel_not_ready - 104008 run_response_stream_failed - 104010 adopted_run_start_not_observed - 104011 session_history_fetch_failed Each entry has a title, summary, and body verified against the throw sites in ably-ai-transport-js (message strings, status codes, cause preservation, and surfacing). protocol/errors.json regenerated via npm run generate:errors. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
|
||
| You will not catch this from a call you made. Because it arises while the SDK is handling an inbound message, it is delivered to the run's `onError` handler if you supplied one, and otherwise emitted on the session's `error` event; handle it in whichever you use. | ||
|
|
||
| If it was `onCancel` that threw, the SDK stopped before cancelling the run, so the run keeps running as if the cancel had not arrived. Cancel it again, once the handler is fixed, if it still needs to stop. |
There was a problem hiding this comment.
Cancel it again, once the handler is fixed, if it still needs to stop.
That doesn't really make sense, because cancel is validate for the duration of an agent run, I don't think it makes sense to talk about patching code while an agent is running. I would just remove this paragraph.
|
|
||
| ## Why it happens | ||
|
|
||
| When a cancel message arrives for a run, the SDK calls your `onCancel` hook; when a steering message folds into a run, it calls your `onSteer` hook. This error is raised when one of them throws, with the thrown value preserved as the `cause`. It also covers an unexpected failure while routing a cancel message to its run. |
There was a problem hiding this comment.
TODO: we should not overload this error code with the cancel-routing failure. We should have a distinct error code for both cancel and steer message routing.
|
|
||
| ## Why it happens | ||
|
|
||
| Two situations raise it. During `connect()`, attaching the channel was rejected; common reasons are the Ably client not being connected, the token lacking the channel's [capabilities](https://ably.com/docs/auth/capabilities), or the channel being in a failed state. The other is a handler throwing at runtime: an inbound message arrived, but processing it (the codec folding it into session state, or a session-level subscription callback) threw. Either way the originating error is preserved as the `cause`. |
There was a problem hiding this comment.
TODO: we should have a separate error code for each case, to allow the developer to handle each accordingly.
| @@ -0,0 +1,18 @@ | |||
| --- | |||
| code: 104003 | |||
| identifier: run_lifecycle_publish_failed | |||
There was a problem hiding this comment.
TODO: we should use the same code for steps, and make this just lifecycle_event_publish_failed
|
Raised AIT-1259 to cover the three TODOs I left here — splitting the overloaded 104001, 104002 and 104003 codes in |
2 participants
Add the AI Transport SDK's own error codes to the registry, from the AIT errors docs page plus the two codes defined in ably-ai-transport-js that the page omits (104010, 104011).
Each entry has a title, summary, and body verified against the throw sites in ably-ai-transport-js (message strings, status codes, cause preservation, and surfacing). protocol/errors.json regenerated via npm run generate:errors.