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
• Error details
• Too many requests

Sample code in the guide

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 send a command:

api.postNewCommand("AirConditioner-Demo", schemaVersion: 1, actions: actions, completionHandler: { (command: Command?, error: ThingIFError?)-> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

When an error occurs in an API call, an error object will be passed as a parameter of the callback method. If there is no error, this error object will have a nil value.

An error returned from an API is notified with the ThingIFError enumerator. For the possible values of ThingIFError, see the Appledoc.

Error details

You can get the details of an error if the value of ThingIFError is ERROR_RESPONSE. ERROR_RESPONSE indicates that the Thing-IF SDK called a REST API and the API returned an error. Such information is useful for determining the root cause of an error, especially during your development.

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:

api.postNewCommand("AirConditioner-Demo", schemaVersion: 1, actions: actions, completionHandler: { (command: Command?, error: ThingIFError?)-> Void in
  if error != nil {
    switch error! {
    case .CONNECTION:
      print("Failed to connect to Thing Interaction Framework")
    case .ERROR_RESPONSE(let errorResponse):
      print("Received an error from Thing Interaction Framework")
      print("httpStatusCode: \(errorResponse.httpStatusCode)")
      print("errorCode: \(errorResponse.errorCode)")
      print("errorMessage: \(errorResponse.errorMessage)")
    default:
      print("Failed for another reason")
    }
    return;
  }
}

Received an error from Thing Interaction Framework
httpStatusCode: 403
errorCode: WRONG_TOKEN
errorMessage: The provided token is not valid

The properties used in this example of an execution result with an invalid access token do not hold a nil value. Depending on the type of an error, you might receive a nil value.

When ERROR_RESPONSE is returned, error details held in the ErrorResponse structure are available. The sample code accesses the properties of the structure by getting them in the errorResponse variable in the switch statement.

• httpStatusCode property

  This property holds a HTTP status code that the REST API returns.

• errorCode property

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

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

• errorMessage property

  This property holds a message for debugging.

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

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 ERROR_RESPONSE as with a case when the REST API returns an execution error. The httpStatusCode property has 429 and the errorCode property and the errorMessage property have a nil 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.