Orkut Application Platform

On-Site Application Developer Guide: Handling Errors

Contents

How do I Handle Errors?

Handling errors is an important part of your application. An error can occur any time you send an OpenSocial request to the Orkut servers, and your application should be able to handle it gracefully.

Errors in OpenSocial calls are signaled through the response object you receive on your callback function. The general pattern is:

var req = opensocial.newDataRequest();

// add individual requests
req.add(req.new..., 'data1');
req.add(req.new..., 'data2');
req.add(req.new..., 'data3');

// send
req.send(callback);

function callback(resp) {
   if (/* error happened */)) {
      // handle error
      return;
   }
}

So how do you detect if an error occurred in the response? The answer is: both the DataResponse object (in our example, that's the type of the resp parameter to the callback() function) and the ResponseItem objects (this is what you get when you call the get() method on a DataResponse) have methods to query for errors.

You can call hadError() on either object to determine if there was an error, and, if so, you can call getErrorCode() to retrieve an error code and getErrorMessage() to retrieve an error message.

Often, the DataRequest will be missing an error message because the error message is reported in the ResponseItem, so you should always print or log all of them.

However, be aware that some times the response items will not be available in a DataResponse, so you should query for them carefully in order to avoid a Javascript error as you try to access an invalid field. Here is an example of error handling that just prints the error details to the debug console (please note that the debug console is only available in OrkutDevBox):

function handleError(resp, items) {
   var tlmsg = resp.getErrorMessage();
   if (typeof(tlmsg) == 'undefined' || tlmsg == null) tlmsg = "";

   debug.say("*** Error: " + tlmsg);
   
   for (var i in items) {
      var item = resp.get(items[i]);
      var prefix = "***   "  + items[i] + ": ";

      if (typeof(item) == 'undefined' || item == 'null')
         debug.say(prefix + "[item unavailable]");
      else if (item.hadError())
         debug.say(prefix + "[" + item.getErrorCode() 
                          + "] " + item.getErrorMessage());
   }
}

This function takes a DataResponse such as the one you would receive on an OpenSocial callback function, and an array of the data keys you are using. These are the parameters you pass to the request's add() function when adding individual requests to the Data Request. Let's see a full example that uses this error-handling function:

var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest("VIEWER"),'myviewer');
req.add(req.newFetchPersonRequest("OWNER"),'myowner');
req.send(callback);

function callback(resp) {
   if (resp.hadError()) {
      handleError(resp, ['myviewer','myowner']);
      return;
   }
   debug.say('success');
}

As you can see, we are passing an array with the strings "viewer" and "owner", which are the same as keys we specified in our calls to req.add.

To test that the error handling is working in the example above, you can introduce an intentional mistake like using VIEWR instead of VIEWER on the request:

var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest("VIEWR"),'myviewer');
req.add(req.newFetchPersonRequest("OWNER"),'myowner');
req.send(callback);

function callback(resp) {
   if (resp.hadError()) {
      handleError(resp, ['myviewer','myowner']);
      return;
   }
   debug.say('success');
}

As a result, the error handling function will print:

*** Error: 
***   myviewer: [badRequest] badRequest: Invalid ID VIEWR

What are the possible error codes?

The possible error codes are defined as constants in the OpenSocial namespace, as specified in the OpenSocial Reference..

Error Code Meaning
opensocial.ResponseItem.Error.BAD_REQUEST Incorrect request syntax or parameters. Check that you are making your request correctly. In particular, check that you are sending all parameters in the format that the call expects. For example, the IdSpec parameter can be tricky, as certain calls expect to receive it as a scalar (string) and others expect it to be an IdSpec object.
opensocial.ResponseItem.Error.FORBIDDEN Your application does not have access to the indicated feature. This may happen, for example, if you the user hasn't given you permission to use a certain feature (like photos), or if you are trying to access a piece of data that is not available to your application due to its current relationship with the viewer (for example, if the viewer does not have your application installed, your access to his or her data is very restricted).
opensocial.ResponseItem.Error.INTERNAL_ERROR An internal error happened on the Orkut servers. This may be because of a problem on our side or because you made an API call in a way that's not supported.
opensocial.ResponseItem.Error.LIMIT_EXCEEDED You've exceeded your quota for certain types of call. For example, sending messages to friends or posting activities have certain limits.
opensocial.ResponseItem.Error.NOT_IMPLEMENTED The operation you tried to invoke hasn't been implemented (yet!)
opensocial.ResponseItem.Error.UNAUTHORIZED Access to the API was denied due to lack of authorization or authentication. The user's session has probably expired. Asking the user to reload the page will probably solve the problem.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.