에러 처리

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 상태로 돌아갑니다.

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' })
  .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)로 전달됩니다.

에러 처리 예시

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가 아님).

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