100ms Logo

100ms

Docs

Search docs
/

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 (i.e. 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 timeframe 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, changRole 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.

Error CodeHMSError.Code Enum Case NameCause of the errorAction to be taken
1003websocketConnectionLostWebsocket disconnected - Happens due to network issuesMention user to check their network connection or try again after some time.
2002invalidEndpointUrlInvalid Endpoint URLCheck the endpoint provided while calling join on HMSSDK.
2003endpointUnreachableEndpoint is not reachableMention user to check their network connection or try again after some time.
2004invalidTokenFormatToken is not in proper JWT formatThe token passed while calling join is not in correct format. Retry getting a new token.
3001cantAccessCaptureDeviceCant Access Capture DeviceAsk user to check permission granted to audio/video capture devices.
3008audiovideoSubsystemFailureSystem media services were reset due to a failure.Restart the session
4001createOfferFailedWebRTC errorSome webRTC error has occurred. Need more logs to debug.
4002createOfferFailedWebRTC errorSome webRTC error has occurred. Need more logs to debug.
4003createOfferFailedWebRTC errorSome webRTC error has occurred. Need more logs to debug.
4004createOfferFailedWebRTC errorSome webRTC error has occurred. Need more logs to debug.
4005iceFailureICE Connection Failed due to network issueMention user to check their network connection or try again after some time.
5001alreadyJoinedTrying to join a room which is already joinedTrying to join an already joined room.
6002unknownwebRTC Error: Error while renegotiatingPlease try again.
401n/aToken Error: Invalid Access KeyAccess Key provided in the token is wrong.
401n/aToken Error: Invalid Room IdRoomID provided in the token is wrong.
401n/aToken Error: Invalid Auth IdAuthID provided in the token is wrong.
401n/aToken Error: Invalid App IdApp ID provided in the token is wrong.
401n/aToken Error: Invalid Customer IdCustomer Id provided in the token is wrong.
401n/aToken Error: Invalid User IdUser ID provided in the token is wrong.
401n/aToken Error: Invalid RoleThe role provided in the token is wrong.
401n/aToken Error: Bad JWT TokenBad JWT Token.
401n/aGeneric ErrorNeed to debug further with logs.
400n/aInvalid RoomRoom ID provided while fetching the token is an invalid room.
400n/aRoom Mismatched with TokenRoom ID provided while fetching the token does not match.
400n/aPeer already joinedPeer who is trying to join has already joined the room.
410n/aPeer is goneThe peer is no more present in the room.

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 (i.e. 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 timeframe 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, changRole 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.

Error CodeHMSError.Code Enum Case NameCause of the errorAction to be taken
1003websocketConnectionLostWebsocket disconnected - Happens due to network issuesMention user to check their network connection or try again after some time.
2002invalidEndpointUrlInvalid Endpoint URLCheck the endpoint provided while calling join on HMSSDK.
2003endpointUnreachableEndpoint is not reachableMention user to check their network connection or try again after some time.
2004invalidTokenFormatToken is not in proper JWT formatThe token passed while calling join is not in correct format. Retry getting a new token.
3001cantAccessCaptureDeviceCant Access Capture DeviceAsk user to check permission granted to audio/video capture devices.
3008audiovideoSubsystemFailureSystem media services were reset due to a failure.Restart the session
4001createOfferFailedWebRTC errorSome webRTC error has occured. Need more logs to debug.
4002createOfferFailedWebRTC errorSome webRTC error has occured. Need more logs to debug.
4003createOfferFailedWebRTC errorSome webRTC error has occured. Need more logs to debug.
4004createOfferFailedWebRTC errorSome webRTC error has occured. Need more logs to debug.
4005iceFailureICE Connection Failed due to network issueMention user to check their network connection or try again after some time.
5001alreadyJoinedTrying to join a room which is already joinedTrying to join an already joined room.
6002unknownwebRTC Error: Error while renegotiatingPlease try again.
401n/aToken Error: Invalid Access KeyAccess Key provided in the token is wrong.
401n/aToken Error: Invalid Room IdRoomID provided in the token is wrong.
401n/aToken Error: Invalid Auth IdAuthID provided in the token is wrong.
401n/aToken Error: Invalid App IdApp ID provided in the token is wrong.
401n/aToken Error: Invalid Customer IdCustomer Id provided in the token is wrong.
401n/aToken Error: Invalid User IdUser ID provided in the token is wrong.
401n/aToken Error: Invalid RoleThe role provided in the token is wrong.
401n/aToken Error: Bad JWT TokenBad JWT Token.
401n/aGeneric ErrorNeed to debug further with logs.
400n/aInvalid RoomRoom ID provided while fetching the token is an invalid room.
400n/aRoom Mismatched with TokenRoom ID provided while fetching the token does not match.
400n/aPeer already joinedPeer who is trying to join has already joined the room.
410n/aPeer is goneThe peer is no more present in the room.