Error Handling

As with any SDK, error handling is a core aspect of maintaining the reliability and robustness when it comes to normal operation. The good news on this front is that the Moonsense SDK does most of the heavy lifting when it comes to tackling the errors that do pop up. There are quite a few retries and recovery mechanisms in place to make sure that the SDK tries its best when addressing the issue at hand before handing over the control to the developer to take the necessary actions to recover from the error. The intention of this document is to help the developer understand the errors reported by the SDK so that they can be handled effectively.

At a high level the SDK uses two mechanisms for reporting errors back to the developer, namely Callbacks and Logging. Callbacks notify the developer in case of any errors reported by the SDK and the Logging framework provides a time based accounting of issues that do show up during runtime.


Each platform defines a Callback that can be registered against the Moonsense singleton that can be used to listen for errors reported by the SDK. As mentioned above, only the non recoverable errors are reported back to the developer i.e. the SDK tries it's best at recovering in case of issues and only reports errors in situations where it cannot proceed. Callbacks can be defined per platform as follows:

val moonsenseCallback = object : MoonsenseCallback { override fun onError(ex: MoonsenseException) { // handle error here } override fun onSessionStarted(session: Session) { // handle the started session here } override fun onSessionStopped(session: Session) { // handle the stopped session here } }
class Callback: MoonsenseDelegate { func errorDidOccur(error: MoonsenseError) { // handle error here } func didStartSession(_ session: Session) { // handle the started session here } func didStopSession(_ session: Session) { // handle the stopped session here } }
const moonsenseCallback = { onSessionError: (msg) => { // handle error here } onSessionStarted: (session) => { // handle the started session here }, onSessionStopped: (session) => { // handle the stopped session here }, }

The error blocks in each Callback return the platform specific error as and when they show up. The user can then choose to handle the error in the way they see fit. You can refer to the documentation for each platform for the specific errors and exceptions:

In general the types of Exceptions you can expect are listed below. Note that what is listed here is not the comprehensive list.

  • Invalid token - This exception is returned for situations where the public token provided to the SDK is invalid or is not in the format expected by the SDK. In situations like these please check the initialization routine to confirm that the token provided is valid.

  • Network error - This exception is returned in cases where the SDK encounters issues communicating with the Moonsense Cloud. The SDK has a recovery mechanism that tries 3 times before quitting just in case the issue is intermittent. In cases like this ensure that the SDK has proper connectivity to complete the network transactions.

  • Permission issues - This error is returned when the SDK does not have the necessary permissions to access the required sensor for data. It is the responsibility of the developer to ensure that the valid permissions have been granted before invoking the call to perform the session recordings. The SDK does not request for permissions on behalf of the user.

  • Initialization error- These are errors encountered during the initialization of the SDK. The SDK is pretty much non functional after returning an initialization error. In such situations make sure that the SDK integration is correct. You can also enable the Logger to determine the exact issue that caused the error.

  • General error - These are generic errors returned by the SDK that do not fall into a specific category. Refer to specific the response message or code to know more about the error and how to handle it.


Developers can also use the logging mechanism used by the SDK to keep an eye on the the errors and diagnostic messages reported by the SDK during normal operation. Developers can set the desired logging by making use of the setLogLevel() method on the Moonsense singleton.

Moonsense.logLevel = .error
const sdkConfig = { publicToken: '<your_public_token>', moonsenseCallback: moonsenseCallback logLevel: 'error', } const moonsenseSdk = new Moonsense(sdkConfig);

The logging returned by the SDK depends on the level that has been set:

  • all - Returns all the events produced by the SDK.

  • debug - Use this setting to keep track of the overall state of the SDK. This level provides debugging information around method calls, lifecycle flows and state management within the Moonsense SDK.

  • notice/warn - Only returns logs around potentially troublesome behavior detected by the SDK. Note that these are just cautions reported by the SDK, there are not necessarily blocking from an operational standpoint but are worth looking into.

  • error - Returns logs around errors detected by the SDK. This setting can be a useful debugging tool to detect incorrect usage patterns, invalid configurations and for general bug triaging.

  • none - Silences the all logging within the SDK i.e. it turns off logging of all events from the Moonsense SDK.

By default the log level on all platforms are set to error and when set each platform reports the logs to their respective logging consoles.