​

WebRTC JS SDK Error Handling

• telnyx.error for structured failures.
• telnyx.warning for degraded but recoverable conditions.
• telnyx.notification for call/session updates plus a small set of backward-compatible notifications.

​

Table of Contents

• Event Overview
• Structured Errors (telnyx.error)
• Structured Warnings (telnyx.warning)
• Notifications (telnyx.notification)
• Call Termination Data
• Socket Events
• Reconnection Behavior
• Legacy RTC Events and Migration

​

Event Overview

​

Structured Errors (telnyx.error)

​

Imports

import {
  SwEvent,
  TelnyxError,
  TELNYX_ERROR_CODES,
  SDK_ERRORS,
  isMediaRecoveryErrorEvent,
} from '@telnyx/webrtc';

• TelnyxError is the structured error class emitted by the SDK.
• isMediaRecoveryErrorEvent() is the type guard for inbound permission recovery flows.
• TELNYX_ERROR_CODES provides named constants for numeric error comparisons.
• SDK_ERRORS provides the registered error metadata.

​

Payload shapes

interface ITelnyxStandardErrorEvent {
  error: ITelnyxError;
  sessionId: string;
  callId?: string;
  recoverable?: false;
}

interface ITelnyxMediaRecoveryErrorEvent {
  error: ITelnyxMediaError;
  sessionId: string;
  callId: string;
  recoverable: true;
  retryDeadline: number;
  resume: () => void;
  reject: () => void;
}

type ITelnyxErrorEvent =
  | ITelnyxStandardErrorEvent
  | ITelnyxMediaRecoveryErrorEvent;

​

Basic example

client.on(SwEvent.Error, (event) => {
  if (isMediaRecoveryErrorEvent(event)) {
    openPermissionsDialog({
      deadline: event.retryDeadline,
      onRetry: () => event.resume(),
      onCancel: () => event.reject(),
    });
    return;
  }

  if (!(event.error instanceof TelnyxError)) {
    showErrorMessage('An unknown SDK error occurred.');
    return;
  }

  switch (event.error.code) {
    case TELNYX_ERROR_CODES.NETWORK_OFFLINE:
      showErrorMessage('You appear to be offline.');
      break;
    case TELNYX_ERROR_CODES.AUTHENTICATION_REQUIRED:
      showErrorMessage('Session expired. Please authenticate again.');
      break;
    default:
      showErrorMessage(event.error.message);
  }
});

​

Error code reference

​

SDP errors

​

Media errors

​

Call-control errors

​

WebSocket and transport errors

​

Authentication and session errors

[!NOTE] Invalid login options currently also include type: ERROR_TYPE.invalidCredentialsOptions on the runtime event payload for backward compatibility. The stable signal to key on is still event.error.code === TELNYX_ERROR_CODES.INVALID_CREDENTIALS.

​

Structured Warnings (telnyx.warning)

​

Payload shape

interface ITelnyxWarningEvent {
  warning: ITelnyxWarning;
  sessionId: string;
  callId?: string;
}

​

Basic example

import { SwEvent, TELNYX_WARNING_CODES, SDK_WARNINGS } from '@telnyx/webrtc';

client.on(SwEvent.Warning, ({ warning, callId }) => {
  if (warning.code === TELNYX_WARNING_CODES.TOKEN_EXPIRING_SOON) {
    refreshTokenSoon();
    return;
  }

  if (warning.code === TELNYX_WARNING_CODES.PEER_CONNECTION_FAILED) {
    showWarningBanner(`Call ${callId ?? ''} is reconnecting`.trim());
    return;
  }

  console.debug(SDK_WARNINGS[warning.code]?.description);
  console.warn(`[${warning.code}] ${warning.name}: ${warning.message}`);
});

​

Warning code reference

​

Network quality warnings

​

Data-flow warnings

​

Connectivity warnings

​

Authentication and session warnings

​

Notifications (telnyx.notification)

​

Important clarification

• telnyx.ready is separate from telnyx.notification.
• The vertoClientReady payload is emitted on telnyx.ready, not on telnyx.notification.

​

Error-related notification types

​

Listener scoping

• onNotification on a call (passed via call options) is the highest-priority hook for that call.
• client.on(SwEvent.Notification, ...) is the session-level fallback that only fires when no call-level listener is registered.
• If no listeners exist at either level, the notification is silently dropped.

​

Screen-share behavior

if (screenShareCall.signalingStateClosed) {
  console.log('This screen-share peer is no longer recoverable.');
}

​

Example: hangup and recovery-aware call updates

client.on(SwEvent.Notification, (notification) => {
  if (notification.type !== 'callUpdate' || !notification.call) {
    return;
  }

  const call = notification.call;

  if (call.recoveredCallId) {
    removeOldCallUi(call.recoveredCallId);
  }

  if (call.state === 'recovering') {
    showConnectionStatus('recovering');
    return;
  }

  if (call.state === 'hangup') {
    console.log('Call ended', {
      cause: call.cause,
      causeCode: call.causeCode,
      sipCode: call.sipCode,
      sipReason: call.sipReason,
    });
  }
});

​

Call Termination Data

​

Socket Events

​

telnyx.socket.close

• code: 1006
• reason: 'STUCK_WS_TIMEOUT: Socket got stuck in CLOSING state and was forcefully cleaned up by safety timeout'
• wasClean: false

​

telnyx.socket.error

{
  error: ErrorEvent | Event;
  sessionId: string;
}

​

Connection state helpers

const placeCall = (destinationNumber: string) => {
  if (!client.connection.connected) {
    showErrorMessage('Still connecting to Telnyx. Please try again shortly.');
    return;
  }

  client.newCall({ destinationNumber });
};

​

Reconnection Behavior

​

What the current SDK does

1. On telnyx.socket.close or telnyx.socket.error, the SDK clears subscriptions and resets gateway readiness state.
2. If autoReconnect is enabled, the browser session schedules connect() after client.reconnectDelay.
3. In the browser session, reconnectDelay is currently 1000 ms.
4. When the gateway reports REGISTER or REGED again, the SDK emits telnyx.ready again.

​

Gateway retry behavior

• UNREGED / NOREG: up to 5 registration retries, each delayed by a random 2 to 6 seconds. After that the SDK emits LOGIN_FAILED (46001).
• FAILED / FAIL_WAIT: GATEWAY_FAILED (45004) is emitted on first detection. If autoReconnect stays enabled, the SDK retries up to 5 times with a random 2 to 6 second delay before RECONNECTION_EXHAUSTED (45003).

​

Keeping media alive across socket loss

• If the peer is still recoverable, the SDK disconnects and reconnects the socket while keeping the call alive.
• If the peer signaling state is already closed, the SDK falls back to a full reconnect path.

​

Recovery and call objects

• The new call exposes recoveredCallId.
• The call may stay in recovering until media/signaling are restored.
• Your UI should remove or merge the old call UI using recoveredCallId.

​

Legacy RTC Events and Migration

​

Legacy or low-level RTC events

​

Migration checklist

1. Add a telnyx.error listener and switch on event.error.code.
2. Add a telnyx.warning listener and switch on warning.code.
3. Keep telnyx.notification for callUpdate and any compatibility notifications you still depend on.
4. Treat telnyx.ready as the only readiness signal.
5. Prefer TELNYX_ERROR_CODES and TELNYX_WARNING_CODES over hard-coded numeric literals.
6. If you support inbound permission recovery, enable mediaPermissionsRecovery and handle isMediaRecoveryErrorEvent(event).