Skip to main content
For backend integrations, use your server SDK’s structured error fields as the source of truth. Server-side integrations should account for session token failures, WebSocket handshake failures, runtime server errors, and unexpected connection closures.

​
Common Server SDK Error Codes

These stable error codes are useful when building retry, logging, and alerting flows on your backend.

​
Server SDK Error Fields

When handling server SDK errors, check these fields to determine the correct recovery path:
  • code: stable SDK error code for programmatic handling
  • phase: where the failure happened, such as session_token, websocket_connect, or websocket_runtime
  • http_status: HTTP status for token or upgrade failures
  • server_code, server_title, server_detail: normalized details returned by the server
  • connection_id, req_id: correlation IDs for tracing requests in logs
  • close_code, close_reason: WebSocket close details for unexpected disconnects
  1. Log code, phase, and correlation IDs (connection_id, req_id).
  2. Retry only transient failures (for example connectionClosed, connectionFailed, idleTimeout).
  3. Surface configuration/auth failures (sessionTokenInvalid, appIDMismatch) to operators.
  4. Alert on recurring upstreamError, serverError, or protocolError.