Exception Handling

Some APIs in the Thing-IF SDK throw exceptions. In this topic, we explain how you can handle the exceptions.

• Sample code in the guides
• Types of exceptions
• Error details
• Too many requests

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. The exception is handled with try and catch blocks following the basic method of exception processing in Java.

For example, we present the following sample code when we explain how to send a command:

try {
  Command command = api.postNewCommand("AirConditioner-Demo", 1, actions);
} catch (ThingIFException e) {
  // Handle the error.
}

If you use JDeferred for implementing your mobile app, you would pass the handler of exception processing to the fail() method of a promise.

In order to get the details of an exception, check the type of the exception object and downcast the exception to the matching type.

mAdm.when(executeApi1()
).fail(new FailCallback<Throwable>() {
  @Override
  public void onFail(final Throwable tr) {
    if (tr instanceof ForbiddenException) {
      // The token was invalid.
    } else if (tr instanceof ThingIFRestException) {
      // An error occurred in Thing Interaction Framework.
      ThingIFRestException restException = (ThingIFRestException)tr;
      Log.i(TAG, "HTTP Status:" + restException.getStatusCode());
    } else if (tr instanceof ThingIFException) {
      // An error occurred in the Thing-IF SDK.
    }
  }
});

Types of exceptions

For the Thing-IF SDK, get the exception data with the ThingIFException class or its subclass. The ThingIFException class is at the root level for the exception classes of the Thing-IF SDK.

The following figure illustrates the exception classes of the Thing-IF SDK:

The Thing-IF SDK uses the exception classes of the com.kii.thingif.exception package. Be careful when you use the APIs of the Thing-IF SDK and the Kii Cloud SDK together because some classes with the same name are included in the com.kii.thingif.exception package of the Thing-IF SDK and the com.kii.cloud.storage.exception.app package of the Kii Cloud SDK.

Execution error of the REST API

When the REST API of Thing Interaction Framework returns an error in response to an API call, the error is notified with the ThingIFRestException class or its subclass.

The Thing-IF SDK returns one of the following exceptions according to the HTTP status code that is returned by the REST API. For the HTTP status codes returned by the REST API, see Thing-IF REST API Documentation.

Validate the length and characters of the returned string with your app before you pass the string to an API as a parameter. Usually, the client SDK checks parameters and notifies any error with a subclass of the RuntimeException class such as java.lang.IllegalArgumentException. Especially, if you implement a catch block with the ThingIFException class, make sure to validate the parameter. Otherwise, your mobile app will not catch a RuntimeException object and crash.

It is difficult to define all the exceptions and error codes thrown by each API in advance. Kii recommends defining only the exceptions that you want to address, such as duplicated users and communication errors, and processing the remaining exceptions as general errors. Exceptions and error codes might be added or updated in newer versions of the SDK and the server.

A process such as getting an owner access token uses APIs of the Kii Cloud SDK. For handling exceptions that occur with those APIs, see Exception Handling for the Kii Cloud SDK.

Error details

Sometimes you can get the details of an error returned by the REST API. Such information is useful for determining the root cause of an error, especially during your development.

This section explains how to get the details of an error returned by the REST API.

You can catch an error returned by the REST API with the ThingIFRestException class or its subclass.

Example of error details

For example, if you disable an owner user before the owner sends a command, their access token becomes invalid and the command sending fails. When this happens, you can get the error details as follows:

try {
  Command command = api.postNewCommand("AirConditioner-Demo", 1, actions);
} catch (ThingIFRestException e) {
  System.out.println("-- class");
  System.out.println(e.getClass());
  System.out.println("-- getStatusCode()");
  System.out.println(e.getStatusCode());
  System.out.println("-- getErrorCode()");
  System.out.println(e.getErrorCode());
  System.out.println("-- getMessage()");
  System.out.println(e.getMessage());
} catch (ThingIFException e) {
  // Handle the error.
}

-- class
class com.kii.thingif.exception.ForbiddenException
-- getStatusCode()
403
-- getErrorCode()
WRONG_TOKEN
-- getMessage()
curl -v -X POST -H 'Content-Type:application/json' -H 'X-Kii-SDK:sn=at;sv=0.11.0;pv=23' -H 'X-Kii-AppID:11111111' -H 'X-Kii-AppKey:22222222222222222222222222222222' -H 'Authorization:Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' 'https://api-jp.kii.com/thing-if/apps/11111111/targets/thing:th.0123456789ab-cdef-0123-4567-89abcdef/commands' -d '{"actions":[{"turnPower":{"power":true}}],"issuer":"user:abcdef012345-6789-abcd-ef01-23456789","schema":"AirConditioner-Dema","schemaVersion":1}'    ## Server Returned HttpStatus:403        The provided token is not valid

This example shows an execution result with an invalid access token. Prepare for cases when not all details are available, such as a case when a value of null is returned.

• getStatusCode() method

  This method returns a HTTP status code that the REST API returns.

• getErrorCode() method

  This method returns a string that indicates the cause of an error. This method is useful when you want to assign a process by error type in your mobile app.

  The return value corresponds to the string in the errorCode field that is one of the error details returned by the REST API.

• getMessage() method

  This method returns error details for debugging.

  Error details vary depending on the error type, including a sample of the curl command that is helpful when you reproduce the error and a REST API message for debugging in the message field.

Kii recommends that you provide error details when you contact Kii Support.

Too many requests

The API returns an 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 an error with the ThingIFRestException class that is a subclass of the ThingIFException class. The getStatusCode() method returns 429 and the getErrorCode() method and the getMessage() method return a null value.

Usually, a mobile app processes this error as an unexpected error on the server. To avoid congestion, do not implement a retry process for executing the API.