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
Common API errors
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:

Blocking API

When you are using a blocking API, you will pass a pointer to an NSError object. When an error occurs, the error information will be put on this error object. The value other than nil means an error.

Swift:

let user = KiiUser(username: "user_123456", andPassword: "123ABC")
do{
  try user.performRegistrationSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

Objective-C:

NSError *error = nil;
KiiUser *user = [KiiUser userWithUsername:@"user_123456"
                              andPassword:@"123ABC"];
[user performRegistrationSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

Non-Blocking API

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

Swift:

let user = KiiUser(username: "user_123456", andPassword: "123ABC")
user.performRegistration { (user :KiiUser?, error : Error?) -> Void in
  if (error != nil) {
    // Handle the error.
    return
  }
}

Objective-C:

KiiUser *user = [KiiUser userWithUsername:@"user_123456"
                              andPassword:@"123ABC"];
[user performRegistrationWithBlock:^(KiiUser *user, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

Error details

Sometimes you can get the details of the error. 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 by checking the NSError's properties. 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. Executing the following code will cause a user duplication error. The sample code shows the error details you can get in this situation.

Swift:

let user = KiiUser(username: "user_123456", andPassword: "123ABC")

do{
  try user.performRegistrationSynchronous()
} catch let error as NSError {
  // Handle the error.

  // Print the error code.
  print("Error code : \(error.code) ")
  // Print the error description.
  print("Error userInfo \(error.userInfo["description"]) ")
  // Print the HTTP status.
  print("Error HTTP status : \(error.kiiHttpStatus()) ")
  // Print the error summary.
  print("Error summary : \(error.kiiErrorSummary()) ")
  // Print the error message from the server.
  print("Error Server error message : \(error.kiiErrorMessage()) ")
  return
}

Objective-C:

NSError *error = nil;
KiiUser *user = [KiiUser userWithUsername:@"user_123456"
                              andPassword:@"123ABC"];
[user performRegistrationSynchronous:&error];
if (error != nil) {
  // Handle the error.

  // Print the error code.
  NSLog(@"Error code : %ld", (long)error.code);
  // Print the error description.
  NSLog(@"Error userInfo : %@", error.userInfo[@"description"]);
  // Print the HTTP status.
  NSLog(@"Error HTTP status : %@", error.kiiHttpStatus);
  // Print the error summary.
  NSLog(@"Error summary : %@", error.kiiErrorSumary);
  // Print the error message from the server.
  NSLog(@"Error Server error message : %@", error.kiiErrorMessage);
  return;
}

Error code : 503
Error description : Duplicate entry exists
Error HTTP status : 409
Error summary : USER_ALREADY_EXISTS
Error Server message : User with loginName user_123456 already exists

This example shows the result of the user duplication. The error information obtainable differs by the situation. In your code, please make sure to handle the case when nil is returned. For example, all REST API related detail will be nil if the error is raised solely by the client SDK inside).

code property

This property returns an error code defined in the KiiError class. For example, 503 (Duplicate entry exists) will be returned when you attempt to register an already-existing user.

Some API returns 0.
description in the userInfo property

This returns an error message that explains the root cause.
kiiHttpStatus property

This returns the HTTP status code returned by Kii Cloud if the client SDK internally executes the REST API. For typical cases, you will not need to explicitly use the HTTP status code in your code. Should you need to use them, you can find the details of the HTTP status code in the REST API reference.
kiiErrorSummary property

This returns the error code in the REST API response. You can use the value if you want to control your code based on the error reason.
kiiErrorMessage property

This returns the error details in the REST API response. This is for debugging purposes.

When you are going to ask for some help, we encourage you to provide this information as the reference.

If you want to control your iOS code based on the error reason, we recommend coding your application as follows:

Check the code property.
If the code property is 0, check the kiiErrorSummary and kiiHttpStatus property to determine the reason.

Common API errors

There are common API errors for cases including when refresh of an access token fails and when the server receives too many requests.

Failed refresh of access tokens

If you are going to leverage the refresh token feature, we encourage you to design your application so as to handle the [KiiError codeRefreshTokenFailed] error.

As explained in Handling token refresh errors, you need to execute relogin with a username and password when you get the RefreshTokenFailedException exception; therefore, your application needs to show the initial screen or the login screen so as to ask for user relogin. This check needs to be made for all API calls that access the network, so it is essential to design how to handle such a situation beforehand.

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 KiiHttpStatus property has HTTP status code 429. The other properties do not have any valid 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.

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.