エラー処理

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

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

エラーコード

エラーコード	分類	説明
SOCKET_FAILED	init	WebSocket接続失敗またはSDKキー検証失敗
STREAMING_FAILED	init	Agoraストリーミング接続失敗
SOCKET_DISCONNECTED_UNEXPECTEDLY	ランタイム	WebSocket異常終了
STREAMING_DISCONNECTED_UNEXPECTEDLY	ランタイム	ネットワーク切断等によるAgora接続切断
SERVER_ERROR	ランタイム	サーバーからSERVER_ERRORシグナル受信
WORKER_DISCONNECTED	ランタイム	サーバー接続終了シグナル受信

initエラー

init() は失敗時に Error をthrowします。SDKは自動的にcleanup後 IDLE 状態に戻ります。

JavaScript

try {
  await SDK.init(options);
} catch (error) {
  console.error(error.message);
}

React

SDK.init({ sdk_key: 'YOUR_SDK_KEY', avatar_id: 'YOUR_AVATAR_ID' })
  .then(() => { initialized.current = true; })
  .catch((error) => console.error(error.message));

init失敗時、onError は呼び出されません。init() が Error をthrowするため、try/catch で処理してください。

message	原因
"Failed to connect: ..."	SDKキー検証またはWebSocket接続失敗
"Failed to connect streaming: ..."	ストリーミング接続失敗

ランタイムエラー

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

ランタイムエラー発生時、SDKは自動的に接続を整理し IDLE 状態に復帰します。 クライアントは onError + onStatus(IDLE) を受信した後、init() で再接続できます。

エラー別状態フロー

エラーコード	発生タイミング	状態遷移
（init throw）	init中	CONNECTING または SOCKET_CONNECTED → IDLE
SOCKET_DISCONNECTED_UNEXPECTEDLY	ランタイム	CONNECTED_FINISH → cleanup → IDLE
STREAMING_DISCONNECTED_UNEXPECTEDLY	ランタイム	CONNECTED_FINISH → cleanup → IDLE
SERVER_ERROR	ランタイム	CONNECTED_FINISH → cleanup → IDLE
WORKER_DISCONNECTED	ランタイム	CONNECTED_FINISH → cleanup → IDLE

initエラーは init() がthrowし、ランタイムエラーは onError コールバック + onStatus(IDLE) で伝達されます。

エラー処理の例

SDK.onError((error) => {
  console.error('SDK Error:', error.code, error.message);
});

エラーコード	message	原因
SOCKET_DISCONNECTED_UNEXPECTEDLY	"WebSocket disconnected unexpectedly: {code}"	WebSocket異常終了
STREAMING_DISCONNECTED_UNEXPECTEDLY	"Streaming disconnected: {reason}"	ネットワーク切断等によるAgora接続切断
SERVER_ERROR	サーバーからのメッセージまたは "SERVER_ERROR"	サーバーからSERVER_ERRORシグナル受信
WORKER_DISCONNECTED	サーバーからのメッセージまたは "WORKER_DISCONNECTED"	サーバー接続終了シグナル受信

処理エラーシグナル

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

SDK.onSignal((data) => {
  if (data.signal === 'ERROR') {
    // サーバー処理中のエラー
    console.warn('エラー:', data.payload?.type);
  }
  if (data.signal === 'REJECTED') {
    // 入力が不正
    console.warn('拒否:', data.payload?.type);
  }
});

シグナル	payload.type例	説明
ERROR	STT_ERROR, LLM_ERROR, TTS_ERROR	サーバー内部処理エラー
REJECTED	STT_EMPTY, MODERATION	入力検証失敗またはポリシー違反