Error Handling

Some APIs in Kii Cloud SDK throw exceptions. In this section, we explain how you can handle the exceptions and how you can investigate the cause of the failure.

Sample code in the guides
Error details
Too many requests
Tools for investigating errors

Sample code in the guides

In the guides, we provide sample code to illustrate how you can leverage our SDKs. In the sample code, the exception handling is usually simplified; the message output and error recovery are omitted.

For example, we present the following sample code when we explain how to register new users. A callback function defined in failure will be called when an error occurs. If you are using Promises, a catch block will be called.

var user = KiiUser.userWithUsername("user_123456", "123ABC");
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    var theUser = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);

var user = KiiUser.userWithUsername("user_123456", "123ABC");
user.register({
  success: function(theUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    // Handle the error.
  }
});

Error details

When an error occurs, the error message is passed to the callback function as a string (errorString in the previous sample code).

The client SDK connects to Kii Cloud server via REST API. When the server returns an error, you can get the information returned by the server using the methods in the exception. The information is useful for determining the root cause of the error during your development.

For example, suppose that you try to register a user user_123456 but this user already exists in Kii Cloud. This will cause a user duplication error, and the following error message will be passed to the callback function.

USER_ALREADY_EXISTS: User with loginName user_123456 already exists

The messages are useful for human to trace the error. To let your program handle the error, you can use the KiiErrorParser method. This method will convert the error message to an object format that can be interpreted by your program easily.

var user = KiiUser.userWithUsername("user_123456", "123ABC");
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    var err = KiiErrorParser.parse(error);
    if (err.status == 0) {
      // The error is related to network.
    } else if (err.status == -1) {
      // The error is not related to network.
      // It might be an argument error or an illegal state error.
    } else if (err.status == -2) {
      // The error is unknown.
      // Confirm the latest version of the SDK is used.
    } else {
      console.log(err.status);
      console.log(err.code);
      console.log(err.message);
    }
  }
);

var user = KiiUser.userWithUsername("user_123456", "123ABC");
user.register({
  success: function(theUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    var err = KiiErrorParser.parse(errorString);
    if (err.status == 0) {
      // The error is related to network.
    } else if (err.status == -1) {
      // The error is not related to network.
      // It might be an argument error or an illegal state error.
    } else if (err.status == -2) {
      // The error is unknown.
      // Confirm the latest version of the SDK is used.
    } else {
      console.log(err.status);
      console.log(err.code);
      console.log(err.message);
    }
  }
});

To translate an error into an object, set the error message passed by a callback function as an argument of the KiiErrorParser.parse(error) method.

The object has the status, code, and message properties:

status: The HTTP status code returned as a result of executing the REST API.

The value such 400 and 404 are usually returned. The value 0 is returned if the request didn't reach the server for some reasons (e.g., network errors). The value -1 is returned if the error message implies that the error is not returned by the server (e.g., argument errors). The SDK returns the value -2 if it cannot identify the error; in this case, you should be able to get the error properly by updating the SDK to the latest version.

Do not implement a retry process for executing the API if 0 is obtained. As described in Too many requests below, it can lead to congestion.
code: The error code in the REST API response.

You can use this string in your program to handle the error based on the detailed error reason. In the case of the user duplication error, for example, you will get the string USER_ALREADY_EXISTS.
message: The error detail included in the HTTP response body returned as a result of executing the REST API.

The message is for an app developer to check and determine the error reason. In the case of the user duplication error, for example, you will get the message User with loginName user_123456 already exists

Please note that Kii Cloud SDK will not throw an exception (e.g. when the parameter is invalid). All errors will be notified to a callback function or a Promise handler.

Too many requests

The API returns error if there are accesses that greatly exceed the ordinary load to the server within a certain period of time for an application. This limit is set per application under an agreement with Kii.

The limit is high enough for ordinary changes in the operational load. However, if active users simultaneously send a request on the same time or event, it could cause an API error.

If the number of API calls exceeds the limit, each API returns error. The parse() method of the KiiErrorParser class returns the status property with a value of 0 as with the case of communication error. To avoid congestion, do not implement a retry process for executing the API if 0 is obtained.

Tools for investigating errors

There are a couple of tools available to help you investigate the error root cause.

Developer log

The error details are recorded in the developer log.

See Inspect Developer Log to learn how you can inspect the error log to spot the root cause while developing and troubleshooting.

The following log is a sample of logs that are recorded when the user duplication occurs:

2015-04-21T11:45:11.783+09:00 [ERROR] user.register description:User registration failed userID: login-name:user_123456 email-address:user_123456@example.com phone-number:+819012345678 exception:User with loginName user_123456 already exists

Data browser

You can verify if the data updated in your application are properly set in Kii Cloud. See Checking and Updating Data, Users, and Groups for more details.