에러 처리

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	입력 검증 실패 또는 정책 위반