Error Handling

Don't have time to dig into details? Here is a minimum error handling code to have in the app:

func on(error: Error) {
    guard let error = error as? HMSError else { return }

    if error.isTerminal {
        showErrorAndExitMeeting(errorMessage: error.localizedDescription)
    } else {
        print(error)
    }
}

Errors happen. When they happen the app needs to react in a manner that makes the most sense to a user. There are 3 major categories of errors:

1. Connection errors (i.e connect lost, unable to connect)
2. Capture device errors (i.e user did not give permission to use microphone)
3. Lack of permissions/authentication errors (that is, auth token is invalid/expired)

While some errors like permissions/authentication errors usually happen during development and are not expected in production, others like connection/device errors are expected to come during normal app lifecycle and require handling in the application code.

Error callbacks

There 2 places where a developer is expected to add error handling:

1. func on(error: HMSError) callback of the HMSUpdateListener
2. Completion handler of the various SDK APIs (i.e endRoom, changeRole etc)

Error Type

The error type in the public SDK interface is Error (NSError in case of ObjC). In swift the error can be type casted to either HMSError or NSError for getting additional details like error code.

Error Handling Example

func on(error: Error) {
    guard let error = error as? HMSError else { return }

    //Example using error constants
    switch error.code {
    case .websocketConnectionLost, .iceFailure, .endpointUnreachable:
        retryConnection()
    default:
		showErrorAndExitMeeting(errorMessage: error.localizedDescription)
        break
    }

    //Example using error codes
    switch error.code.rawValue {
    case 1003, 4005, 2003:
        retryConnection()
    default:
		showErrorAndExitMeeting(errorMessage: error.localizedDescription)
        break
    }
}

HMSError Properties

isTerminal

The HMSError struct in swift will now have an isTerminal property which denotes wether error has caused the current session to terminate and the app will need to call join again to reconnect. Same will be available via is_terminal (HMSIsTerminalUserInfoKey constant) key in userInfo dictionary of NSError

canRetry

The HMSError struct in swift will now have an canRetry property which denotes wether app can call join again with the same configuration it has used before. The value be false in cases like token expiring or room getting locked. You can use this property while implementing infinite retry in your app. Same will be available via can_retry (HMSCanRetryUserInfoKey constant) key in userInfo dictionary of NSError

Error Handling Example Using Properties

This example shows the minimal error handling you can have in the app without worrying about error codes.

func on(error: Error) {
    guard let error = error as? HMSError else { return }

    if error.isTerminal {
        if error.canRetry && isInfiniteRetryEnabledInApp  {
            retryConnection()
        } else {
            showErrorAndExitMeeting(errorMessage: error.localizedDescription)
        }
    } else {
        logError(message: error.localizedDescription)
    }
}

Connection Errors

When for whatever reason the internet connection becomes unavailable the SDK will first try to automatically reconnect. Upon failing to reconnect within a time frame of 50 seconds SDK will give up and send an error via onError callback of HMSUpdateListener

There are 3 error codes you can expect in this scenario:

1. websocketConnectionLost (1003)
2. iceFailure (4005)
3. endpointUnreachable (2003)

When the application gets any of these it can react by calling join again as in an infinite retry, or it can bring user to the previous screen showing an error popup.

Capture Device Errors

Typically when the SDK can’t get a hold of a capture device i.e the user has not given access permission it will send an onError callback with cantAccessCaptureDevice (3001). If the microphone/camera access are crucial to the experience you are trying to build the app should end the meeting and show an error popup, otherwise user can continue participating without camera/mic in a listen/watch only mode.

API Errors

When issuing certain API calls like endRoom, changeRole etc you might get en error in return. This might be due to lack of permissions for a current role or server getting overloaded etc.

Error Code List

Following are the different error codes that are returned by the SDK.