WebRTC Flutter SDK Error Handling

This document describes the error handling mechanisms in the Telnyx WebRTC Flutter SDK, specifically focusing on when and why error events are triggered and how they are processed through the SDK.

The Flutter SDK implements a structured approach to error handling through several key components:

1. OnSocketErrorReceived Callback: Defines a callback function that is triggered when socket errors occur
2. TelnyxSocketError Class: Provides a data structure for encapsulating error states
3. TelnyxErrorConstants Class: Defines standard error codes and messages used throughout the SDK
4. Network Connectivity Monitoring: Detects and handles network changes and connectivity issues
5. Gateway State Management: Monitors the gateway registration status and triggers errors when appropriate

The SDK monitors the gateway registration status and triggers errors in the following scenarios:

• When the gateway status is "FAILED" after registration attempts
• When the gateway registration times out
• Location: telnyx_client.dart
• This ensures that the client is properly connected to the Telnyx network

Example:

case GatewayState.failed:
  GlobalLogger().i('GATEWAY REGISTRATION FAILED :: ${stateMessage.toString()}');
  gatewayState = GatewayState.failed;
  final error = TelnyxSocketError(
    errorCode: TelnyxErrorConstants.gatewayFailedErrorCode,
    errorMessage: TelnyxErrorConstants.gatewayFailedError,
  );
  onSocketErrorReceived(error);

The SDK handles gateway registration timeout:

• When the gateway registration process takes too long to complete
• Location: telnyx_client.dart
• This helps applications handle situations where the gateway is unreachable

Example:

GlobalLogger().i('GATEWAY REGISTRATION TIMEOUT');
final error = TelnyxSocketError(
  errorCode: TelnyxErrorConstants.gatewayTimeoutErrorCode,
  errorMessage: TelnyxErrorConstants.gatewayTimeoutError,
);
onSocketErrorReceived(error);

The SDK handles error messages received through the WebSocket connection:

• When the server sends an error message via WebSocket
• Location: telnyx_client.dart - _onMessage method
• These errors typically indicate issues with the connection or server-side problems

Example:

if (data.toString().trim().contains('error')) {
  final errorJson = jsonEncode(data.toString());
  _logger.log(
    LogLevel.info,
    'Received WebSocket message - Contains Error :: $errorJson',
  );
  try {
    final ReceivedResult errorResult =
        ReceivedResult.fromJson(jsonDecode(data.toString()));
    onSocketErrorReceived.call(errorResult.error!);
  } on Exception catch (e) {
    GlobalLogger().e('Error parsing JSON: $e');
  }
}

The SDK detects network connectivity problems and reports them as errors:

• When network is lost during an active session
• When network type changes (e.g., from WiFi to mobile data)
• Location: telnyx_client.dart - _handleNetworkLost method
• These errors help applications handle offline scenarios gracefully

Example:

void _handleNetworkLost() {
  for (var call in activeCalls().values) {
    call.callHandler.onCallStateChanged
        .call(CallState.dropped.withReason(NetworkReason.networkLost));
  }
}

The TelnyxSocketError class provides a standardized way to handle errors throughout the SDK:

class TelnyxSocketError {
  int errorCode = 0;
  String errorMessage = '';

  TelnyxSocketError({required this.errorCode, required this.errorMessage});

  TelnyxSocketError.fromJson(Map<String, dynamic> json) {
    errorCode = json['code'] ?? 0;
    errorMessage = json['message'] ?? '';
  }
}

This class encapsulates:

• An error code that identifies the type of error
• An error message describing what went wrong

The SDK defines standard error constants in the TelnyxErrorConstants class:

class TelnyxErrorConstants {
  static const tokenError = 'Token registration error';
  static const tokenErrorCode = -32000;
  static const credentialError = 'Credential registration error';
  static const credentialErrorCode = -32001;
  static const gatewayTimeoutError = 'Gateway registration timeout';
  static const gatewayTimeoutErrorCode = -32003;
  static const gatewayFailedError = 'Gateway registration failed';
  static const gatewayFailedErrorCode = -32004;
  static const callNotFound = 'Call not found';
}

These constants provide consistent error reporting across the SDK.

The SDK uses the CallState enum to track the state of calls, including error states:

enum CallState {
  // Other states...
  
  /// [reconnecting] The call is reconnecting - for this state a [NetworkReason] is provided.
  reconnecting,

  /// [dropped] The call has been dropped - for this state a [NetworkReason] is provided.
  dropped,
  
  /// [error] there was an issue creating the call.
  error;
  
  // Methods to handle reasons...
}

When network issues occur, calls can transition to the dropped or reconnecting states with an associated NetworkReason:

enum NetworkReason {
  /// The network has been switched.
  networkSwitch('Network switched'),

  /// The network has been lost.
  networkLost('Network lost'),

  /// The network has adjusted due to Airplane mode.
  airplaneMode('Airplane mode enabled');

  /// The message associated with the network reason.
  final String message;

  const NetworkReason(this.message);
}

To handle errors in your application, you should implement the onSocketErrorReceived callback:

telnyxClient.onSocketErrorReceived = (TelnyxSocketError error) {
  // Log the error
  print('Telnyx Socket Error: ${error.errorMessage} (${error.errorCode})');

  // Handle specific error types
  switch (error.errorCode) {
    case TelnyxErrorConstants.gatewayFailedErrorCode:
      // Handle gateway registration failure
      attemptReconnection();
      break;
    case TelnyxErrorConstants.gatewayTimeoutErrorCode:
      // Handle gateway timeout
      showTimeoutMessage();
      break;
    default:
      // Handle other types of errors
      showErrorToUser(error.errorMessage);
      break;
  }
};

When implementing error handling for the Telnyx WebRTC Flutter SDK:

1. Always implement the onSocketErrorReceived callback: This is the primary channel for receiving error notifications
2. Log errors for debugging purposes: Capture error messages for troubleshooting
3. Implement appropriate error recovery mechanisms: Different errors may require different recovery strategies
4. Display user-friendly error messages: Translate technical error messages into user-friendly notifications
5. Implement reconnection logic when appropriate: For network or gateway issues, automatic reconnection may be appropriate
6. Monitor call state changes: Watch for dropped, reconnecting, and error states to handle call-specific issues

• Cause: Network connectivity issues or invalid credentials
• Solution: Check network connection and credential validity, then attempt reconnection

• Cause: Server unreachable or network latency issues
• Solution: Implement retry mechanism with exponential backoff

• Cause: Network interruption or server issues
• Solution: Implement automatic reconnection with exponential backoff

• Cause: Device switching between WiFi and mobile data, or losing connectivity
• Solution: Monitor network state changes and implement appropriate UI feedback and reconnection logic

• Telnyx WebRTC Flutter SDK GitHub Repository
• API Documentation