Error handling

A number of errors might occur when using Apideo. For instance, the user's connection might be lost, or a firewall might prevent connecting to Apideo servers... By default, Apideo's behaviour is to pop an alert box in the user's browser. This is very convenient for development, but is certainly not what you want for production sites. This page will teach you how to handle errors gracefully.

Available error handlers

Since most errors can occur asynchronously, there is no way to use a try .. catch statement to manage errors. Therefore, in Apideo, errors are managed like events, by registering listeners.

There are 7 error handlers:

• Global error handler: any error that occurs in Apideo and that is not managed by another error handler is forwarded to the global error handler.
• Room error handler: any error that occurs in a room and that is not managed by a more specific error handler is catched by this handler. For instance, this handler will receive all errors related to connection problems (unable to join room, connection to room suddenly lost, etc...)
• Camera error handler: any error that occurs while starting a camera or sending a video stream can be catched by the camera error handler.
• Stream error handler: any error that occurs when trying to view a stream can be catched by the stream error handler.
• Room/Camera/Stream securiy error handlers: There are special event handlers defined for the security related issues. Security errors are only triggered when the access to the application is denied because of a token. See token-based security if you want to learn more about what can be allowed and denied.

Catching errors

Catching errors is easy. To catch any error (using the global error handler), just use this code:

// Global error handler
Apideo.onError(function(category, type, msg) {
    // Your code to handle the error goes here.
});

As you will notice, there are 3 parameters passed to the functio handling the errors:

• category: The category of the error
• type: The type, or subcategory of the error
• msg: A plain text message, in English, explaining the error

The list of all error categories and error types can be be accessed in this annex.

// Room error handler
room.onError(function(category, type, msg) {
    // Your code to handle the error goes here.
});
 
// Room security error handler
room.onSecurityError(function(category, type, msg) {
    // Your code to handle the error goes here.
});
 
// Camera error handler
camera.onError(function(category, type, msg) {
    // Your code to handle the error goes here.
});
 
// Camera security error handler
camera.onSecurityError(function(category, type, msg) {
    // Your code to handle the error goes here.
});
 
// Viewer error handler
viewer.onError(function(category, type, msg) {
    // Your code to handle the error goes here.
});
 
// Viewer security error handler
viewer.onSecurityError(function(category, type, msg) {
    // Your code to handle the error goes here.
});

A sample application: trying to reconnect automatically

Using error handlers, it is easy to catch any connection error and retry connecting instead of failing. Here is a sample code that will try to reconnect:

// Error handler timeout
errorHandlerTimeOutId = null;
 
/**
 * The joinMyRoom function performs the connection.
 */
function joinMyRoom() {
	myRoom = myConnection.joinRoom("myRoom");
 
	/**
	 * The error handler will try to reconnect
	 * If any error happens, let's disconnect and reconnect, 
	 * but after waiting 10 seconds.
	 */
	myRoom.onError(function(category, type, message) {
		if (category == "connect") {
			if (errorHandlerTimeOutId != null) 
				return;
 
			// Here, we would put the code to reinitialize any part 
			// of the UI that needs to be changed on error
 
			errorHandlerTimeOutId = setTimeout(function(){
				errorHandlerTimeOutId = null;
 
				// Now, let's reconnect!
				joinMainRoom();
 
			}, 10000);
		} else {
			alert("An error was detected while connecting: "+category+"-"+type+":"+message);
		}
	});
}