Error Codes

Asleep.setDebugLoggerDelegate()

let delegate: AsleepDebugLoggerDelegate = self
Asleep.setDebugLoggerDelegate(self)
protocol AsleepDebugLoggerDelegate {
    func didPrint(message: String)
}
Property NameTypeDescription
messageStringLog message

Asleep.setLogger()

구조화된 로거 AsleepLogger 를 등록할 수 있습니다. 기존 setDebugLoggerDelegate 는 그대로 동작하며, 새 프로젝트는 setLogger 를 사용할 수 있습니다.

let logger: AsleepLogger = self
Asleep.setLogger(logger)
protocol AsleepLogger {
    func d(tag: LogTag, msg: String, error: Error?)
    func e(tag: LogTag, msg: String, error: Error?)
    func i(tag: LogTag, msg: String, error: Error?)
    func w(tag: LogTag, msg: String, error: Error?)
}
MethodDescription
dDebug 레벨 로그
eError 레벨 로그
iInfo 레벨 로그
wWarning 레벨 로그

각 메서드는 로그 분류용 태그 LogTag(tracking, recording, upload 등), 메시지, 에러(옵셔널)를 전달받습니다.

Asleep.AsleepError

enum AsleepError: Error {
    case unknown(systemError: Error)
    case shouldResume
    case over24hours
    case audioInitializationFailed
    case cannotActivateInBackground
    case unableODA
    case setupIncomplete   // v3.3.2
    case startTrackingNetworkFail(code: Int, message: String?)   // deprecated (v3.3.2)
    case stopTrackingNetworkFail(code: Int, message: String?)    // deprecated (v3.3.2)
    case responseResult(endpoint: String)
    case httpStatus(code: Int, errorCode: Int?, message: String?)   // deprecated

    case networkOffline
    case configurationError
    case alreadyTracking
    case sessionCleanupFailed
    case sessionCreateFailed
    case recorderStartFailed
    case trackingStartFailed
    case interruptionRecoveryFailed(attemptsCount: Int)
    case uploadTrackingTerminated(message: String?)

    // v3.3.0
    case invalidParameter(message: String?)
    case insufficientStorage(message: String?)
    case completeTimeout(message: String?)
    case saveMetadataFailed(message: String?)
    case fetchMetadataFailed(message: String?)
    case metadataValidationFailed(message: String?)
    case productRegisterFailed(message: String?)
    case productRegisterRejected(message: String?)

    // v3.3.0 — Token authentication
    case tokenIssueFailed(message: String?)
    case tokenRefreshFailed(message: String?)
    case tokenInvalidCredentials(message: String?)
    case tokenNetworkError(message: String?)
}

unknown: 알 수 없는 시스템 에러

  • systemError: Error - 시스템이 발생한 에러

shouldResume: 마이크 녹음 인터럽트 이후 재개할 수 없음

over24Hours: 녹음이 24시간 초과되어 강제 중지함

  • 에이슬립 SDK는 24시간을 초과하는 수면 측정을 지원하지 않습니다.

audioInitializationFailed: 오디오 관련 하드웨어 설정 오류

  • iOS 디바이스 오디오 초기화 오류
    • Audio 설정 초기화를 위해 createSleepTrackingManager() 다시 호출

cannotActivateInBackground: 인터럽트 종료시 마이크 재시작에 실패할 경우 발생하는 오류

  • 앱이 백그라운드에 있어 iOS 가 마이크 재시작을 막은 경우입니다.
  • 앱이 포그라운드로 돌아오면 SDK 가 자동으로 녹음을 재개합니다. 사용자에게 notification 등으로 앱을 열도록 알려 주세요. Asleep.SleepTrackingManager.resumeTracking() 을 직접 호출해도 됩니다.

startTrackingNetworkFail: startTracking 초기화 시 발생 하는 네트워크 오류 (deprecated, v3.3.2)

  • code: Int - 400 이상의 http code
  • message: String - 에러 사유 설명

stopTrackingNetworkFail: stopTracking 시 발생 하는 네트워크 오류 (deprecated, v3.3.2)

  • code: Int - 400 이상의 http code
  • message: String - 에러 사유 설명

responseResult: api reponse의 result값에 문제가 발생함

  • endpoint - 문제가 발생한 endpoint

httpStatus: http 에러

  • code: Int - 400 이상의 http code
  • errorCode: Int? - 5자리 SDK 에러 코드(베타). 아래 5자리 SDK 에러 코드 (베타) 참고
  • message: String - 에러 사유 설명

v3.3.0 에서 추가된 케이스

Case발생 상황앱이 할 일
invalidParameter요청을 보내기 전 파라미터 검증 실패. 분석 구간의 시작 시각이 종료 시각보다 늦거나 같을 때입력값 확인
insufficientStorage녹음 파일 저장에 필요한 여유 공간이 부족해 측정을 시작하지 못함저장 공간 안내
completeTimeout측정 종료 후 30초 안에 분석 완료를 확인하지 못함. 측정 실패가 아니며 세션은 정상 종료됨잠시 후 report(sessionId:) 로 조회
saveMetadataFailed사용자 메타데이터 저장 실패 (네트워크 · 서버 오류, userId 미설정)재시도
fetchMetadataFailed사용자 메타데이터 조회 실패 (네트워크 · 서버 오류, userId 미설정)재시도
metadataValidationFailed메타데이터 값이 허용 범위를 벗어남. 서버 요청 전에 던지며, 3.3.2부터 서버가 400 으로 거절한 경우도 이 케이스(서버 문구 포함)로 전달입력값 확인
productRegisterFailed기기(Product) 등록 일시 실패. 네트워크 · 서버 오류(5xx) · 요청 과다(429). SDK 가 재시도한 뒤의 결과잠시 후 setup 재호출
productRegisterRejected기기(Product) 등록 거부. 입력값 오류(400) · 인증 실패(401) · 등록 권한 없음(403). 다시 시도해도 결과가 같음productInfo / API Key 확인
tokenIssueFailed토큰 발급 실패네트워크 확인 후 재시도
tokenRefreshFailed토큰 갱신 실패네트워크 확인 후 재시도
tokenInvalidCredentials잘못된 appId / appSecret (3.3.2부터 토큰 발급 401 · 404 도 포함)앱 인증 정보 확인 (재시도해도 결과 동일)
tokenNetworkError토큰 요청 중 네트워크 오류네트워크 확인 후 재시도

v3.3.2 에서 추가된 케이스

Case발생 상황앱이 할 일
setupIncompleteODA 를 켠 setup 이 아직 끝나지 않았는데 측정을 시작함 (3.3.1 까지는 unableODA)setup 완료 콜백을 받은 뒤 측정 시작

각 케이스의 message 는 원인 확인(로그)용이며 문구가 예고 없이 바뀔 수 있습니다. 앱 로직은 케이스 또는 5자리 번호로 분기하세요.

🚧

케이스는 v3.3.x 동안 그대로 유지됩니다.

  • 리포트 조회(report / reports / averageReport) · 재분석 · 유저 삭제 · 메타데이터의 서버 오류, 그리고 업로드 5xx 오류는 httpStatus(code:errorCode:message:) 로 전달됩니다.
  • 세션 생성 오류는 startTrackingNetworkFail, 세션 종료 오류는 stopTrackingNetworkFail, 업로드 4xx 오류는 uploadTrackingTerminated 로 전달됩니다.
  • startTrackingNetworkFail · stopTrackingNetworkFail · httpStatus 에는 deprecated 경고가 붙지만 동작은 같으며, v4.0.0 전까지 그대로 전달됩니다.

어느 케이스로 오든 error.errorCode 에는 원인별 5자리 코드(베타)가 들어 있어, 3.3.2 부터 switch error.errorCode 로 분기할 수 있습니다. 케이스 정리와 5자리 코드의 정식 전환은 v4.0.0 에 예정되어 있습니다.


5자리 SDK 에러 코드 (베타)

3.2.0 부터 AsleepError 의 errorCode 로 5자리 SDK 에러 코드가 전달됩니다(베타). 3.3.2 에서 번호를 원인별로 정리했고, 번호 이름으로 switch 할 수 있게 되었습니다. 정식 전환은 v4.0.0 에 예정되어 있습니다. 3.3.1 에서 바뀐 번호는 에러 번호와 측정 상태(v3.3.2) 를 참고하세요.

func didFail(error: Asleep.AsleepError) {
    switch error.errorCode {
    case .createConflict:   // 22409
        // 이전 세션이 아직 닫히지 않음
        break
    case .commonExpired:    // 11403
        // 플랜 만료 · 요청 과다
        break
    default:
        print(error.errorCode.code, error.errorCode.message ?? "")
    }
}
  • errorCode.code: 5자리 번호
  • errorCode.message: 서버가 보낸 문구가 있으면 그 문구, 없으면 기본 문구. 원인 확인용이며 예고 없이 바뀔 수 있습니다.
  • AsleepErrorCode 의 == 는 번호만 비교합니다 (3.3.2). [.uploadFailed].contains(error.errorCode) 처럼 써도 문구와 관계없이 동작합니다.

번호의 앞 두 자리는 기능, 뒤 세 자리는 원인입니다. 뒤 세 자리가 000 이면 서버 응답이 없거나(인터넷 없음 등) 분류되지 않은 실패, 4xx · 500 이면 해당 HTTP 상태입니다.

ODA (10xxx)

Code이름설명
10000setupIncompleteODA setup 이 끝나지 않았는데 측정 시작 (v3.3.2)
10001unableODAODA 를 사용할 수 없음 (3.3.2 부터 모델 파일 손상도 포함)

SDK 기본 (11xxx)

Code이름설명
11000unknown알 수 없는 오류
11001uninitializedSDK 가 초기화되지 않음
11002micPermission마이크 권한 없음
11003audio오디오 초기화 · 녹음기 시작 실패
11004invalidURL잘못된 URL
11005audioSilenced소리가 들어오지 않음
11006audioUnsilenced소리가 다시 들어옴
11007interruptionRecoveryFailed인터럽트 뒤 재개 실패 (iOS 전용)
11008insufficientStorage저장 공간 부족
11009invalidParameter파라미터 검증 실패
11010alreadyTracking이미 측정 중인데 startTracking() (v3.3.2)
11401commonUnauthorized인증 실패
11403commonExpired플랜 만료 · 요청 과다 · 사용량 초과
11404commonNotFound사용자 · 대상을 찾을 수 없음
11500network서버 오류

토큰 (12xxx) · 기기 등록 (13xxx)

Code이름설명
12000tokenIssueFailed토큰 발급 실패
12001tokenRefreshFailed토큰 갱신 실패
12002tokenInvalidCredentials잘못된 appId / appSecret (발급 401 · 404)
12003tokenNetworkError토큰 요청 중 네트워크 오류
13000productRegisterFailed기기 등록 일시 실패
13400productRegisterRejected기기 등록 거부

init (21xxx)

Code이름설명
21000initFailedinit 실패 (인터넷 없음 포함)
21500initServerErrorinit 서버 오류

세션 생성 (22xxx)

Code이름설명
22000createFailed세션 생성 실패 (응답 없음 등)
22400createBadRequest잘못된 요청 (v3.3.2)
22401createUnauthorized인증 실패
22409createConflict이전 세션이 아직 닫히지 않음
22422createValidation파라미터 오류
22500createServerError서버 오류

세션 생성의 403 · 429 는 11403, 404 는 11404 로 전달됩니다.

업로드 (23xxx)

Code이름설명
23000uploadFailed업로드 실패 (응답 없음 등). 측정은 계속됨
23400uploadBadRequest잘못된 업로드 요청
23401uploadUnauthorized인증 실패
23403uploadForbidden이미 닫힌 세션
23404uploadNotFound없는 세션
23413uploadTooLarge업로드 크기 초과
23422uploadUnprocessable잘못된 순번
23499uploadTrackingTerminated업로드 4xx 로 측정 종료
23500uploadServerError서버 오류. 측정은 계속됨

세션 종료 (24xxx)

Code이름설명
24000closeFailed종료 실패 (응답 없음 등)
24400closeBadRequest잘못된 종료 요청
24401closeUnauthorized인증 실패
24403closeForbidden이미 닫힌 세션
24404closeNotFound없는 세션
24500closeServerError서버 오류

삭제 (25xxx · 26xxx)

Code이름설명
25000deleteFailed세션 삭제 실패
25401deleteUnauthorized세션 삭제 인증 실패
25500deleteServerError세션 삭제 서버 오류
26000deleteUserFailed사용자 삭제 실패 (인터넷 없음 포함)
26401deleteUserUnauthorized사용자 삭제 인증 실패
26500deleteUserServerError사용자 삭제 서버 오류

사용자 삭제의 404 는 11404 로 전달됩니다.

메타데이터 (27xxx) · 분석 완료 (28xxx)

Code이름설명
27000saveMetadataFailed메타데이터 저장 실패
27100fetchMetadataFailed메타데이터 조회 실패
27400metadataValidationFailed메타데이터 값 오류 (SDK 사전 검사 · 서버 400)
28000completeTimeout분석 완료를 30초 안에 확인하지 못함 (측정 실패 아님)

재분석 (30xxx)

Code이름설명
30000reanalyzeFailed재분석 실패
30400reanalyzeBadRequestInvalid start_time/end_time
30401reanalyzeUnauthorizedReanalyse unauthorized
30403reanalyzeForbiddenThe customer is not allowed to reanalyse the session
30404reanalyzeNotFoundSleep session not found
30409reanalyzeConflictReanalysis is already in progress
30410reanalyzeGoneThe data retention period has expired
30422reanalyzeUnprocessableThe session is still being tracked
30500reanalyzeServerErrorReanalyse server error

분석 요청 (31xxx)

Code이름설명
31000analyseFailed분석 요청 실패
31400analyseBadRequest잘못된 타임존
31401analyseUnauthorized인증 실패
31404analyseNotFound세션을 찾을 수 없음
31500analyseServerError서버 오류

리포트 (32xxx · 33xxx · 34xxx)

Code이름설명
32000reportFailed리포트 조회 실패 (인터넷 없음 포함)
32400reportBadRequest잘못된 사용자 ID
32401reportUnauthorized인증 실패
32404reportNotFound리포트를 찾을 수 없음
32500reportServerError서버 오류
33000reportsFailed리포트 목록 실패 (인터넷 없음 포함)
33400reportsBadRequest잘못된 타임존
33401reportsUnauthorized인증 실패
33500reportsServerError서버 오류
34000averageReportFailed평균 리포트 실패 (인터넷 없음 포함)
34400averageReportBadRequest기간이 너무 김
34404averageReportNotFound사용자를 찾을 수 없음
34500averageReportServerError서버 오류
📘

ODAIntegrityFail(10002) 와 sseConnectFailed(22600) 는 3.3.2 부터 보내지 않는 번호이며 deprecated 입니다.

HTTP Status code

State: COMMON, INIT, TRACKING, REPORT

CodeTypeDescriptionStateHandling
401UnauthorizedUnauthorizedCOMMONClient Handling
401Unauthorizedinvalid user idCOMMONClient Handling
403Plan is expiredPlan is expiredCOMMONSDK Stop
403Rate limit exceededRate limit exceededCOMMONSDK Stop
403Quota exceededQuota exceededCOMMONSDK Stop
400Bad RequestInvalid callback urlTRACKINGClient Handling
400Bad Request[WARNING] Invalid session end time. format(YYYY-MM-DDTHH:mm:ssz), 'session_end_time' must always be greater than 'session_start_time’TRACKINGSDK Handling
403Forbiddenthe sleep session is already closedTRACKINGSDK Stop
404Not Foundsession does not exist.TRACKINGClient Handling
409Conflictprevious sleep session is not closed yetTRACKINGSDK Stop
422Validation ErrorInvalid parameterTRACKINGSDK Handling
422Unprocessable EntityInvalid parameter.TRACKINGSDK Handling
400Bad Requestinvalid timezoneREPORTClient Handling
400Unprocessable EntityThe format of sleep session id {session_id} is not validREPORTClient Handling
401UnauthorizedThe api key is not providedREPORTClient Handling
404Not FoundUnable to find the sleep session of id {session_id}REPORTClient Handling

SDK Error 대응을 위한 정의

SDK 구간 동작에 대한 정의

  • Init (initAsleepConfig) : SDK 초기화 상태
  • Tracking (SleepTrackingManager): 수면 모니터링을 위한 Audio Recording 환경과 Server의 통신 프로토콜 관리
  • Report (Reports): 수면 모니터링 결과

Error Case Definition

  • SDK Stop: SDK 내부에서 종료 처리. SDK 내부적으로 종료 처리 되어서 새로 시작을 위해서는 SDK 재시작 필요. SDK 상태에 따라서 자체적으로 Session 종료 및 Audio Recording 기능에 대한 종료 처리됨. initAsleepConfig 요청 부터 새로 시작해야 SDK 활성화
  • SDK Handling: SDK 내부적으로 Error 업데이트 후 다음 동작을 수행. 에러 수신 후 종료 처리를 하고 싶으면 SDK 호출된 상태에 따라서 처리가 필요. SDK 종료 처리를 위해서는 Tracking 상태에서만 stopTracking 호출해 줘야 하고 다른 구간에서는 별도 처리 필요 없음.
  • Client Handling: Client에서 조치를 해줘야 하는 에러. 개발시 Error 확인 용도
  • Do not used: 현재 버전에서 사용되고 있지 않는 에러

Error Handling 분류

  • SDK 사용시 주로 나오는 Error Code는 붉은 색으로 표시. 취소선으로 선택된 Error Code는 나올 확률이 낮음.

Did this page help you?