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

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.

In the sample code with promises, the error is handled with an exception handler specified in the catch() method. You can catch the error details as an instance of the ThingIFError class.

  • api.postNewCommand(commandRequest).then((command: ThingIF.Command) => {
  // Do something.
}).catch((error: ThingIF.ThingIFError) => {
  // Handle the error.
});
  • api.postNewCommand(commandRequest).then(
  function(command) {
    // Do something.
  }
).catch(
  function(error) {   // error: ThingIFError
    // Handle the error.
  }
);

The ThingIFError class is available only with the Thing-IF SDK APIs. If you combine APIs of the Kii Cloud SDK and Thing-IF SDK with a promise chain, be careful that the type of an error received with the catch() method is not always ThingIFError.

Types of exceptions

For the Thing-IF SDK, get the exception data with the ThingIFError class or its subclass. The ThingIFError 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 ThingIFError class is implemented as a subclass of the BaseError class of make-error-cause.

When the REST API of Thing Interaction Framework returns an error, the error is notified with the HttpRequestError class.

Error details

You can get the details of an error with the ThingIFError class and the HttpRequestError class as below.

Note that the KiiErrorParser class of the Kii Cloud SDK does not support errors that occur in the Thing-IF SDK.

ThingIFError

The ThingIFError class handles errors that occur in the Thing-IF SDK in general.

  • The name property stores a string that indicates the type of error. It is one of these strings:

    Symbol Value Description
    ThingIF.Errors.ArgumentError ArgumentError One or more invalid API arguments were specified.
    ThingIF.Errors.HttpError HttpRequestError A REST API error of Thing Interaction Framework occurred. For more information, see the HttpRequestError section below.
    ThingIF.Errors.IlllegalStateError IlllegalStateError The execution condition of the API was invalid.
    ThingIF.Errors.NetworkError NetworkError A network error occurred.

  • The message property stores an error message.

HttpRequestError

The HttpRequestError class handles errors that occur on the server as a result of executing an API of the Thing-IF SDK. An instance of this class stores "HttpRequestError" in the name property.

For more information about error details, see error codes in the Thing Interaction Framework (Thing-IF) API reference.

  • The status property stores a HTTP status code that the REST API returns.

  • The errorCode property stores an error code of the REST API. Use this value to handle the error in your program.

  • The message property stores an error message from the REST API.

  • The rawData property stores entire error information from the REST API.

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:

  • if (error instanceof ThingIF.ThingIFError) {
  console.log("ThingIFError-----");
  console.log(error.name);
  console.log(error.message);
}
if (error instanceof ThingIF.HttpRequestError) {
  console.log("HttpRequestError-----");
  console.log(error.status);
  console.log(error.body.errorCode);
  console.log(error.body.message);
  console.log(error.body.rawData);
}
  • if (error instanceof ThingIF.ThingIFError) {
  console.log("ThingIFError-----");
  console.log(error.name);
  console.log(error.message);
}
if (error instanceof ThingIF.HttpRequestError) {
  console.log("HttpRequestError-----");
  console.log(error.status);
  console.log(error.body.errorCode);
  console.log(error.body.message);
  console.log(error.body.rawData);
}
ThingIFError-----
HttpRequestError
The provided token is not valid
HttpRequestError-----
403
WRONG_TOKEN
The provided token is not valid
{"errorCode":"WRONG_TOKEN","message":"The provided token is not valid","appID":"11111111","accessToken":"1111111111111111111111111111111111111111111"}

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 of the Thing-IF SDK returns an error with the ThingIFError class. The error object has "NetworkError" in the name property and "Unable to connect to <Kii Cloud URL>" in the message property as with a case when the REST API returns a general network error. Depending on the web browser in use, a response with the HTTP status code 429 is recorded in a JavaScript log that can be viewed with a developer tool included in the browser.

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.