Klleon SDK

日本語

한국어
English

日本語

한국어
English

Appearance

エラー処理 ​

SDKエラーは3つの経路で伝達されます:

  1. initエラー — init() が Error 例外を発生させる
  2. ランタイムエラー — onError コールバックで伝達
  3. 処理エラー — onSignal で ERROR/REJECTED シグナルとして伝達（セッション維持）

エラーコード ​

init の失敗はエラーコードなしで init() の例外として伝えられます。

エラーコード分類説明
STREAMING_FAILEDランタイムリモートトラック購読失敗 — 接続は維持される
SOCKET_DISCONNECTED_UNEXPECTEDLYランタイムWebSocket異常終了
STREAMING_DISCONNECTED_UNEXPECTEDLYランタイムネットワーク切断等によるAgora接続切断
SERVER_ERRORランタイムサーバーからSERVER_ERRORシグナル受信
WORKER_DISCONNECTEDランタイムサーバー接続終了シグナル受信

initエラー ​

init() は失敗すると例外を発生させます。SDKは内部の接続リソースを整理し、IDLE 状態に戻ります。

js
try {
  await SDK.init(options);
} catch (error) {
  console.error(error.message);
}
jsx
SDK.init({ sdk_key: 'YOUR_SDK_KEY', avatar_id: 'YOUR_AVATAR_ID' })
  .catch((error) => console.error(error.message));

初期化の失敗自体は onError ではなく init() の例外(reject)として伝えられます。ただし接続中のストリーミング側の問題で onError が併発する場合があるため、onError の登録は init() 呼び出し前に行うのが安全です。

message原因
"Failed to connect: ..."SDKキー検証またはWebSocket接続失敗
"Failed to connect streaming: ..."ストリーミング接続失敗
"Init failed: ..."その他の初期化失敗

ランタイムエラー ​

init以降、接続中に発生するエラーです。onError コールバックで伝達されます。

ランタイムエラー発生時、SDKは自動的に接続を整理し IDLE 状態に復帰します。 クライアントは onError + onStatus(IDLE) を受信した後、init() で再接続できます。 ただし STREAMING_FAILED（リモートトラック購読失敗）は例外です — 接続の整理や IDLE への復帰は行われず、onError のみ伝達されます。

エラー別状態フロー ​

エラーコード発生タイミング状態遷移
（init 例外）init中CONNECTING または SOCKET_CONNECTED → IDLE
STREAMING_FAILEDランタイム状態遷移なし — onError のみ伝達、接続維持
SOCKET_DISCONNECTED_UNEXPECTEDLYランタイムCONNECTED_FINISH → 接続リソースの整理 → IDLE
STREAMING_DISCONNECTED_UNEXPECTEDLYランタイムCONNECTED_FINISH → 接続リソースの整理 → IDLE
SERVER_ERRORランタイムCONNECTED_FINISH → 接続リソースの整理 → IDLE
WORKER_DISCONNECTEDランタイムCONNECTED_FINISH → 接続リソースの整理 → IDLE

initエラーは init() が例外として発生させ、ランタイムエラーは onError コールバック + onStatus(IDLE) で伝達されます。

エラー処理の例 ​

js
SDK.onError((error) => {
  console.error('SDK Error:', error.code, error.message);
});
エラーコードmessage原因
STREAMING_FAILED"Failed to subscribe to remote track"リモートトラック購読失敗 — 接続維持、onError のみ伝達
SOCKET_DISCONNECTED_UNEXPECTEDLY"WebSocket disconnected unexpectedly: {code}" または "Handover failed after max retries and active socket is dead"WebSocket異常終了
STREAMING_DISCONNECTED_UNEXPECTEDLY"Streaming disconnected: {reason}" または "Remote user left streaming"ネットワーク切断等によるAgora接続切断
SERVER_ERRORサーバーからのメッセージまたは "SERVER_ERROR"サーバーからSERVER_ERRORシグナル受信
WORKER_DISCONNECTEDサーバーからのメッセージまたは "WORKER_DISCONNECTED"サーバー接続終了シグナル受信

処理エラーシグナル ​

ERROR、REJECTED シグナルはセッションを終了しません。個別リクエストに対する失敗を示します。 onSignal で受信します（onError ではありません）。

js
SDK.onSignal((data) => {
  if (data.signal === 'ERROR') {
    // サーバー処理中のエラー
    console.warn('エラー:', data.payload?.type);
  }
  if (data.signal === 'REJECTED') {
    // 入力が不正
    console.warn('拒否:', data.payload?.type);
  }
});
シグナルpayload.type例説明
ERRORSTT_ERROR, LLM_ERROR, TTS_ERRORサーバー内部処理エラー
REJECTEDSTT_EMPTY, MODERATION入力検証失敗またはポリシー違反