​

Error Handling

​

What your application should react to

Version note: The structured error and warning system (TELNYX_ERROR_CODES, telnyx.warning, TelnyxError) was introduced after v2.25.25. Exponential-backoff reconnection and browser online/offline hints (see Reconnection Behavior) ship in the next release. If you are on v2.25.25, see Error handling in v2.25.25 below.

​

Structured Errors (telnyx.error)

​

Imports

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

​

Error event payload structure

interface ITelnyxStandardErrorEvent {
  error: ITelnyxError;     // structured error (TelnyxError instance)
  sessionId: string;       // SDK session identifier
  callId?: string;         // present when the error is tied to a call
  recoverable?: false;     // usually absent — see note below
}

interface ITelnyxMediaRecoveryErrorEvent {
  error: ITelnyxMediaError; // one of 42001 / 42002 / 42003
  sessionId: string;
  callId: string;
  recoverable: true;        // the only positive recovery signal
  retryDeadline: number;   // epoch ms after which the SDK stops waiting
  resume: () => void;       // retry media acquisition after permissions are fixed
  reject: () => void;       // abort recovery and let the call fail
}

fatal vs recoverable — two distinct fields, two distinct purposes:

• event.error.fatal (always present on every error): tells your app whether the SDK has a recovery path. true = the SDK will not recover — take action now. false = the SDK is handling it — wait or continue.
• event.recoverable (only on media-permission recovery events): signals the app can recover via the resume()/reject() helpers. Only event.recoverable === true is meaningful; recoverable is absent on standard errors — do not branch on event.recoverable === false.

Recommended listener order: (1) check isMediaRecoveryErrorEvent(event) first, (2) then check event.error.fatal to decide whether to take action or wait, (3) then branch on event.error.code for tailored UX.

​

Getting and filtering errors by code

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

client.on(SwEvent.Error, (event) => {
  // 1. Media-permission recovery path (only when configured)
  if (isMediaRecoveryErrorEvent(event)) {
    openPermissionsDialog({
      deadline: event.retryDeadline,
      onRetry: () => event.resume(),
      onCancel: () => event.reject(),
    });
    return;
  }

  // 2. Guard against non-structured errors (legacy/edge paths)
  if (!(event.error instanceof TelnyxError)) {
    showErrorMessage('An unknown SDK error occurred.');
    return;
  }

  // 3. Branch on the numeric code — always compare against TELNYX_ERROR_CODES
  switch (event.error.code) {
    case TELNYX_ERROR_CODES.SESSION_NOT_REATTACHED:
      // Fatal: server lost the call after reconnect
      terminateCallUi(event.callId);
      showErrorMessage('The call could not be recovered. Please place the call again.');
      break;

    case TELNYX_ERROR_CODES.LOGIN_FAILED:
    case TELNYX_ERROR_CODES.INVALID_CREDENTIALS:
      // Fatal: re-authenticate without recreating the client
      refreshTokenAndLogin();
      break;

    case TELNYX_ERROR_CODES.RECONNECTION_EXHAUSTED:
      // Fatal: automatic reconnect gave up
      showReconnectButton();
      break;

    case TELNYX_ERROR_CODES.MEDIA_MICROPHONE_PERMISSION_DENIED:
    case TELNYX_ERROR_CODES.MEDIA_DEVICE_NOT_FOUND:
    case TELNYX_ERROR_CODES.MEDIA_GET_USER_MEDIA_FAILED:
      showMediaError(event.error.message);
      break;

    default:
      showErrorMessage(event.error.message);
  }
});

​

Media permission recovery

const client = new TelnyxRTC({
  login_token: jwt,
  mediaPermissionsRecovery: {
    enabled: true,
    timeout: 10000,
  },
});

client.on(SwEvent.Error, (event) => {
  if (isMediaRecoveryErrorEvent(event)) {
    // Show a dialog asking the user to grant microphone permission
    // event.retryDeadline is the timestamp by which they must act
    showPermissionDialog({
      onGrant: () => event.resume(),
      onDismiss: () => event.reject(),
    });
  }
});

​

Fatal errors and recommended handling

Uncommon errors — when to investigate. SDP_CREATE_OFFER_FAILED (40001), SDP_CREATE_ANSWER_FAILED (40002), SDP_SET_LOCAL_DESCRIPTION_FAILED (40003), SDP_SET_REMOTE_DESCRIPTION_FAILED (40004), PEER_CLOSED_DURING_INIT (44005), and WEBSOCKET_CONNECTION_FAILED (45001) are not expected during normal operation. If any of these recurs a few times or more, share the call with Telnyx support for investigation — their occurrence is most likely not caused by user actions and may indicate a browser, network, or server-side issue.

• AUTHENTICATION_REQUIRED (46003) is non-fatal by default but becomes fatal when autoReconnect: false. Re-authenticate using client.login().
• The three media errors (42001–42003) become recoverable (non-fatal) when mediaPermissionsRecovery.enabled is set.

Re-authenticate without recreating the instance. For LOGIN_FAILED (46001), INVALID_CREDENTIALS (46002), and AUTHENTICATION_REQUIRED (46003), use client.login() on the existing connection:

// Refresh token without recreating TelnyxRTC
await client.login({ creds: { login_token: newToken } });

​

Errors and warnings you should handle explicitly

​

Error code reference

​

SDP errors

​

Media errors

​

Call-control errors

​

ICE restart errors

​

WebSocket and transport errors

autoReconnect is enabled by default. Unless you explicitly set autoReconnect: false, the SDK handles reconnection automatically for WEBSOCKET_ERROR, GATEWAY_FAILED, and signaling-health recovery. You only need to call client.connect() manually if you disabled autoReconnect or after RECONNECTION_EXHAUSTED.

​

Authentication and session errors

Re-authenticate without recreating the instance. For LOGIN_FAILED (46001), INVALID_CREDENTIALS (46002), and AUTHENTICATION_REQUIRED (46003), use client.login() to re-authenticate on the existing connection:

// Refresh token without recreating TelnyxRTC
await client.login({ creds: { login_token: newToken } });

​

Structured Warnings (telnyx.warning)

​

Imports

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

​

Warning event payload structure

interface ITelnyxWarningEvent {
  warning: ITelnyxWarning; // structured warning (plain object, not an Error)
  sessionId: string;
  callId?: string;
}

// Added on recovery warnings:
//   reason?: string                                        // human-readable reason
//   source?: 'probe' | 'request' | 'peer_failure' | 'no_rtp' // SIGNALING_RECOVERY_REQUIRED only

​

Getting and filtering warnings by code

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

client.on(SwEvent.Warning, (event) => {
  const { warning, sessionId, callId, reason, source } = event;

  switch (warning.code) {
    case TELNYX_WARNING_CODES.TOKEN_EXPIRING_SOON:
      refreshToken();
      break;

    case TELNYX_WARNING_CODES.PEER_CONNECTION_FAILED:
      showWarningBanner('Call is reconnecting');
      break;

    case TELNYX_WARNING_CODES.SIGNALING_RECOVERY_REQUIRED:
      // source tells you what triggered recovery: 'probe' | 'request' | 'peer_failure' | 'no_rtp'
      showReconnectingBanner(`Signaling recovery (${source})`);
      break;

    case TELNYX_WARNING_CODES.MEDIA_RECOVERY_REQUIRED:
      showReconnectingBanner('Media reconnecting');
      break;

    case TELNYX_WARNING_CODES.MULTIPLE_ACTIVE_CALLS_DETECTED:
      logMultiCall(callId, sessionId);
      break;

    case TELNYX_WARNING_CODES.RECONNECTION_FAILED_WITH_NO_AUTO_RECONNECT:
      showReconnectButton();
      break;

    default:
      console.warn(`[${warning.code}] ${warning.name}: ${warning.message}`);
  }
});

​

Warning code reference

​

Network quality warnings

​

Data-flow warnings

​

Call connection warnings

​

Authentication and session warnings

​

Signaling health and recovery warnings

• If signaling is unhealthy, it reconnects the WebSocket and reattaches active calls (SIGNALING_RECOVERY_REQUIRED).
• If signaling is healthy but media is unhealthy, it attempts ICE restart (MEDIA_RECOVERY_REQUIRED).
• It does not run both recovery paths at the same time.

​

Call Termination Data

​

Socket Events

​

telnyx.socket.close

​

telnyx.socket.error

​

Connection State Helpers

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

  client.newCall({ destinationNumber });
};

​

Reconnection Behavior

​

Reconnect backoff

• Base delay starts at ~1s and doubles per attempt (~1s → ~2s → ~4s → ~8s → ~16s), capped at 30s.
• ±25% jitter is applied to avoid thundering-herd reconnects.
• The backoff counter resets only on a confirmed healthy registration (REGED), not merely on socket open.

​

Browser online/offline handling

• offline emits the NETWORK_OFFLINE (48001) error for backward compatibility/telemetry and may accelerate a signaling health probe. It does not force a reconnect.
• online clears the browser-reported offline state for diagnostics but does not trigger recovery.
• Recovery starts only from SDK-owned health evidence: liveness probe timeout, critical request timeout, peer failure, or no-RTP.

​

Socket close/error dedupe

​

Gateway retry behavior

• UNREGED / NOREG: Up to 5 registration retries with exponential backoff. After that, LOGIN_FAILED (46001).
• FAILED / FAIL_WAIT / TIMEOUT: GATEWAY_FAILED (45004) emitted on first detection. The SDK retries with exponential backoff until RECONNECTION_EXHAUSTED (45003).

​

Keeping media alive

​

Clearing reconnect stickiness

// Before reconnecting
client.clearReconnectToken();

// Or configure the SDK to skip the last voice SDK ID on reconnect
const client = new TelnyxRTC({
  login_token: jwt,
  skipLastVoiceSdkId: true,
});

Note: clearReconnectToken() and skipLastVoiceSdkId are available in @telnyx/webrtc@2.26.4.

​

Error Handling in v2.25.25

Important: If you are using SDK version 2.25.25, the error handling architecture is fundamentally different from the current version. This section documents the v2.25.25 error surface.

​

What is different in v2.25.25

​

Error events in v2.25.25

client.on(SwEvent.Error, (event) => {
  // event.error is a plain Error object — no structured code
  // event.type may include ERROR_TYPE.invalidCredentialsOptions
  // event.sessionId is available
  console.error('SDK error:', event.error?.message || event.error);
});

client.on(SwEvent.Notification, (notification) => {
  switch (notification.type) {
    case 'userMediaError':
      // notification.error — raw browser Error/DOMException
      // notification.errorName — error name string
      // notification.errorMessage — error message string
      // notification.call — the Call object (if available)
      // SDK automatically hangs up the call
      showPermissionPrompt(notification.errorMessage);
      break;

    case 'peerConnectionFailureError':
      // notification.error — raw error
      // Peer connection failed, but the call may be recovered by the server
      // via attach with 'recovering' state. Show degraded UI and wait.
      showReconnectingBanner();
      break;

    case 'signalingStateClosed':
      // Peer signaling state closed — peer is not recoverable
      // But the call may still recover through server attach
      // Only clean up after a final hangup/callUpdate confirms loss
      showReconnectingBanner();
      break;

    case 'callUpdate':
      // Normal call lifecycle
      handleCallUpdate(notification.call);
      break;
  }
});

​

Authentication errors in v2.25.25

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

client.on(SwEvent.Error, (event) => {
  if (event.type === ERROR_TYPE.invalidCredentialsOptions) {
    // Credentials were invalid before the request was sent
    showLoginError('Please check your credentials.');
    return;
  }

  // For LOGIN_FAILED or AUTHENTICATION_REQUIRED, re-login without recreating the instance:
  // await client.login({ creds: { login_token: newToken } });

  // Other errors — generic handling
  showErrorMessage(event.error?.message || 'An error occurred');
});

​

Reconnection in v2.25.25

• autoReconnect is enabled by default; the SDK automatically reconnects unless you set autoReconnect: false
• Reconnect uses a fixed/random 2-6 second delay (current SDK uses exponential backoff with jitter, capped at 30s)
• Browser online/offline events directly drive reconnect (current SDK treats them as low-confidence hints)
• No maxReconnectAttempts option (current SDK defaults to 10 attempts and supports maxReconnectAttempts: 0 for unlimited attempts)
• No clearReconnectToken() method
• No skipLastVoiceSdkId option
• keepConnectionAliveOnSocketClose is available

​

Migrating from v2.25.25 to the latest

1. Replace telnyx.notification error handling — use telnyx.error for fatal errors and telnyx.warning for non-fatal conditions. Keep telnyx.notification for call lifecycle only.
2. Replace notification.type === 'userMediaError' handling with telnyx.error listener switching on event.error.code (42001, 42002, 42003).
3. Replace notification.type === 'peerConnectionFailureError' handling with telnyx.warning listener for PEER_CONNECTION_FAILED (33004).
4. Replace notification.type === 'signalingStateClosed' handling with telnyx.warning listener for the appropriate warning code.
5. Replace ERROR_TYPE.invalidCredentialsOptions checks with event.error.code === TELNYX_ERROR_CODES.INVALID_CREDENTIALS (46002). Use client.login() to re-authenticate without recreating the TelnyxRTC instance.
6. Import new symbols: TelnyxError, TELNYX_ERROR_CODES, TELNYX_WARNING_CODES, isMediaRecoveryErrorEvent.
7. Note SESSION_NOT_REATTACHED is an error, not a warning: in v2.26.0+ it is TELNYX_ERROR_CODES.SESSION_NOT_REATTACHED (48501) on telnyx.error (fatal), not a warning. UNKNOWN_REATTACHED_SESSION (35002) is the separate warning.