Exception Handling

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

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 things:

ret = kii_thing_authenticate(&kii, VENDOR_THING_ID, PASSWORD);
if (ret != 0) {
  /* Handle the error. */
  return;
}

Error details

When the SDK connects to the Kii Cloud server and it returns an error, you can get the error detail. It helps to identify the cause of the problem, especially in the development phase.

For example, suppose that you try to register a thing whose vendorThingID is rBnvSPOXBDF9r29GJeGS but this thing has already been registered to Kii Cloud. Executing the following code will cause a thing duplication error. The sample code shows the error details you would get in this situation.

#define VENDOR_THING_ID "rBnvSPOXBDF9r29GJeGS"
#define THING_TYPE "sensor"
#define PASSWORD "123ABC"

ret = kii_thing_register(&kii, VENDOR_THING_ID, THING_TYPE, PASSWORD);
if (ret != 0) {
  /* Handle the error. */
  printf("status code:%d\n", kii.kii_core.response_code);
  printf("error string:%s\n", kii.kii_core.response_body);
  return;
}

status code:409
error string:{
  "errorCode" : "THING_ALREADY_EXISTS",
  "message" : "Thing with vendorThingID rBnvSPOXBDF9r29GJeGS already exists",
  "value" : "rBnvSPOXBDF9r29GJeGS",
  "field" : "vendorThingID"
}

The kii.kii_core.response_code stores the HTTP status code defined in the REST API. The meaning of the code depends on the REST API executed by the SDK API. Review the source code for the called SDK API and see References for the status code defined in the REST API.

The kii.kii_core.response_body stores the error information from the REST API as a JSON string. See Parsing JSON to learn how to get fields from such a JSON string.

These fields are especially important in the error information:

  • errorCode

    This field stores the error code for the failed execution. Use this field to determine the execution result in your program.

  • message

    This field stores the error details in a human-readable format. In this example, you can find that the specified thing has already been registered.

To handle the program with the error type, write code to use the kii.kii_core.response_code after you confirm that the HTTP status code is not shared by multiple types of errors. If you need more information because the HTTP status code is shared, parse the JSON string in the kii.kii_core.response_body to get the errorCode field and branch processes.

Kii recommends that you provide the content of the kii.kii_core.response_body when you contact Kii Support.

Resetting error code

You will not receive any error details if an error occurs before the request is sent to Kii Cloud. For example, if the buffer size is smaller than the message size of the REST API to send, the function will return a non-0 value. At this time, the kii.kii_core.response_code and the kii.kii_core.response_body will keep the values before the API call.

To check if the server has responded or not in the program, Kii recommends that you add an initialization step as below before calling the API. This makes it easier to detect an error which occurs before the request is sent to Kii Cloud.

kii.kii_core.response_code = 0;
kii.kii_core.response_body = NULL;

Tools to investigate errors

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

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 recorded when the thing duplication occurs:

2016-06-17T14:08:21.000+09:00 [ERROR] thing.create description:New thing creation failed  exception:Thing with vendorThingID rBnvSPOXBDF9r29GJeGS 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.