例外処理

Thing-IF SDK の API には、呼び出しによって例外が発生するものがあります。ここでは、例外への対処処理の詳細について示します。

サンプルコードでの記載
例外の型
詳細情報の取得
負荷集中時のエラー

サンプルコードでの記載

本ガイドのサンプルコードでは、エラーハンドリングの必要箇所のみを示し、詳細（メッセージの出力やエラーからの回復処理など）は省略しています。

本ガイドで示す Promise のサンプルコードでは、catch() メソッドに指定された例外処理のハンドラーにエラー処理を記述します。この際、ThingIFError クラスのインスタンスとしてエラーの詳細を受け取ることができます。

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.
  }
);

ThingIFError クラスは Thing-IF SDK の API のみで使用されます。Kii Cloud SDK と Thing-IF SDK の API を Promise チェーンで連結する場合、catch() メソッドで受け取るエラーの型は必ずしも ThingIFError クラスにならない点にご注意ください。

例外の型

Thing-IF SDK を利用する際は、ThingIFError クラス、または、そのサブクラスによって例外の情報を取得します。ThingIFError は Thing-IF SDK で扱う例外クラスのルート階層に位置するクラスです。

Thing-IF SDK が扱う例外クラスには以下のものがあります。

ThingIFError クラスは make-error-cause の BaseError クラスのサブクラスとして実装されています。

また、API を実行した際、Thing Interaction Framework の REST API がエラーを返すと、HttpRequestError クラスでエラーが通知されます。

詳細情報の取得

エラーが発生したとき、詳細情報は、ThingIFError クラスと HttpRequestError クラスから、それぞれ以下のように取得できます。

なお、Kii Cloud SDK の KiiErrorParser は Thing-IF SDK のエラーには対応していません。

ThingIFError

ThingIFError は、Thing-IF SDK で発生したエラー全般を扱うクラスです。

name プロパティには発生したエラーの種類を表す文字列が格納されています。以下の文字列のいずれかの値を取ります。

シンボル	値	説明
ThingIF.Errors.ArgumentError	ArgumentError	API の引数が正しくないことを表します。
ThingIF.Errors.HttpError	HttpRequestError	Thing Interaction Framework の REST API のエラーを表します。詳細は下記の HttpRequestError の説明を参照してください。
ThingIF.Errors.IlllegalStateError	IlllegalStateError	API の実行条件が正しくないことを表します。
ThingIF.Errors.NetworkError	NetworkError	ネットワークエラーを表します。

message プロパティには、エラーメッセージが格納されています。

HttpRequestError

HttpRequestError は、Thing-IF SDK の API を実行した結果、サーバーで発生したエラーを扱うクラスです。このインスタンスでは、name プロパティに "HttpRequestError" を保持しています。

エラーの詳細は、Thing Interaction Framework（Thing-IF）API リファレンスに記載されているエラーコードを参照してください。

status プロパティには REST API を実行した際の HTTP のステータスコードが格納されています。
errorCode プロパティには REST API のエラーコードが格納されています。プログラムで制御する場合はこの値を使用します。
message プロパティには REST API のエラーメッセージが格納されています。
rawData プロパティには REST API のエラー情報全体が格納されています。

詳細情報の例

たとえば、コマンドを送信する直前にオーナーユーザーの無効化を行うと、アクセストークンが無効になってコマンドの送信に失敗します。この際、取得できる詳細情報の例は次のとおりです。

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"}

負荷集中時のエラー

サーバーに対して、一定時間内に通常の負荷を大きく超えるアクセスが発生した場合、そのアプリケーションでは API がエラーを返します。この制限値は、利用契約に基づいてアプリケーションごとに定められます。

この制限値には余裕があるため、通常の運用負荷の変動では問題なく動作する設計ですが、例えば特定の時刻にアクティブユーザーが一斉にリクエストを行うような機能はエラーの発生につながります。

上限に達した場合、Thing-IF SDK の各 API は ThingIFError クラスでエラーを返します。この際、返されるエラーは、name プロパティに "NetworkError" を、message プロパティに "Unable to connect to <Kii Cloud の URL>" という文字列を保持します（一般的な接続エラーと同じです）。なお、Web ブラウザーによっては、デベロッパーツールなどで確認できる JavaScript のログに、HTTP ステータス 429 での応答が行われたことが記録されます。

通常、モバイルアプリでは、このエラーをサーバーでの想定外エラーとして処理できますが、輻輳を防止するため、API の再試行は避けるように実装してください。