docs: document Server AI Toolkit session and WebSocket error codes

[ozdemircibaris]

Warning

Do not merge until WS Migration Part 7b (/stream-tool) ships in the Server AI Toolkit repo. These errors are only reachable via the live-session path that endpoint introduces, so merging earlier would document behavior the API doesn't expose yet. Ready for review now.

What

Documents the session and WebSocket error codes introduced by the WebSocket migration in the Server AI Toolkit REST API reference (rest-api.mdx).

• Error envelope — documents the REST error shape ({ error: { message, status, code } }) and the code field, which wasn't covered before.
• Streaming and session errors — a new section explaining that /stream-tool works on the document over a live connection and surfaces connection/concurrency errors in-band as an error event ({ "type": "error", "code", "status", "message" }), not as an HTTP status. Includes a table of the seven codes with status, cause, and how to handle each:
  • concurrent_edit_conflict, schema_mismatch, websocket_auth_failed, websocket_connection_failed, websocket_sync_timeout, session_limit_reached, session_creation_cancelled
• Handle concurrent edits — a focused subsection on concurrent_edit_conflict (the original issue) with retry guidance and an example, since it's expected behavior in collaborative documents.
• Cross-links the /stream-tool endpoint to the new error section.

Why it's blocked

The session layer that throws these errors isn't wired into any merged endpoint yet — only into /stream-tool (WS Migration Part 7b), which lives in the Server AI Toolkit repo and is still in review, with its response format marked "still being finalized." Documenting against /execute-tool (the REST path) would be inaccurate.

Closes TT-494

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tiptap-docs	Ready	Preview, Comment	Jun 1, 2026 10:30am