각 메서드는 로그 분류용 태그 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
발생 상황
앱이 할 일
setupIncomplete
ODA 를 켠 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
이름
설명
10000
setupIncomplete
ODA setup 이 끝나지 않았는데 측정 시작 (v3.3.2)
10001
unableODA
ODA 를 사용할 수 없음 (3.3.2 부터 모델 파일 손상도 포함)
SDK 기본 (11xxx)
Code
이름
설명
11000
unknown
알 수 없는 오류
11001
uninitialized
SDK 가 초기화되지 않음
11002
micPermission
마이크 권한 없음
11003
audio
오디오 초기화 · 녹음기 시작 실패
11004
invalidURL
잘못된 URL
11005
audioSilenced
소리가 들어오지 않음
11006
audioUnsilenced
소리가 다시 들어옴
11007
interruptionRecoveryFailed
인터럽트 뒤 재개 실패 (iOS 전용)
11008
insufficientStorage
저장 공간 부족
11009
invalidParameter
파라미터 검증 실패
11010
alreadyTracking
이미 측정 중인데 startTracking() (v3.3.2)
11401
commonUnauthorized
인증 실패
11403
commonExpired
플랜 만료 · 요청 과다 · 사용량 초과
11404
commonNotFound
사용자 · 대상을 찾을 수 없음
11500
network
서버 오류
토큰 (12xxx) · 기기 등록 (13xxx)
Code
이름
설명
12000
tokenIssueFailed
토큰 발급 실패
12001
tokenRefreshFailed
토큰 갱신 실패
12002
tokenInvalidCredentials
잘못된 appId / appSecret (발급 401 · 404)
12003
tokenNetworkError
토큰 요청 중 네트워크 오류
13000
productRegisterFailed
기기 등록 일시 실패
13400
productRegisterRejected
기기 등록 거부
init (21xxx)
Code
이름
설명
21000
initFailed
init 실패 (인터넷 없음 포함)
21500
initServerError
init 서버 오류
세션 생성 (22xxx)
Code
이름
설명
22000
createFailed
세션 생성 실패 (응답 없음 등)
22400
createBadRequest
잘못된 요청 (v3.3.2)
22401
createUnauthorized
인증 실패
22409
createConflict
이전 세션이 아직 닫히지 않음
22422
createValidation
파라미터 오류
22500
createServerError
서버 오류
세션 생성의 403 · 429 는 11403, 404 는 11404 로 전달됩니다.
업로드 (23xxx)
Code
이름
설명
23000
uploadFailed
업로드 실패 (응답 없음 등). 측정은 계속됨
23400
uploadBadRequest
잘못된 업로드 요청
23401
uploadUnauthorized
인증 실패
23403
uploadForbidden
이미 닫힌 세션
23404
uploadNotFound
없는 세션
23413
uploadTooLarge
업로드 크기 초과
23422
uploadUnprocessable
잘못된 순번
23499
uploadTrackingTerminated
업로드 4xx 로 측정 종료
23500
uploadServerError
서버 오류. 측정은 계속됨
세션 종료 (24xxx)
Code
이름
설명
24000
closeFailed
종료 실패 (응답 없음 등)
24400
closeBadRequest
잘못된 종료 요청
24401
closeUnauthorized
인증 실패
24403
closeForbidden
이미 닫힌 세션
24404
closeNotFound
없는 세션
24500
closeServerError
서버 오류
삭제 (25xxx · 26xxx)
Code
이름
설명
25000
deleteFailed
세션 삭제 실패
25401
deleteUnauthorized
세션 삭제 인증 실패
25500
deleteServerError
세션 삭제 서버 오류
26000
deleteUserFailed
사용자 삭제 실패 (인터넷 없음 포함)
26401
deleteUserUnauthorized
사용자 삭제 인증 실패
26500
deleteUserServerError
사용자 삭제 서버 오류
사용자 삭제의 404 는 11404 로 전달됩니다.
메타데이터 (27xxx) · 분석 완료 (28xxx)
Code
이름
설명
27000
saveMetadataFailed
메타데이터 저장 실패
27100
fetchMetadataFailed
메타데이터 조회 실패
27400
metadataValidationFailed
메타데이터 값 오류 (SDK 사전 검사 · 서버 400)
28000
completeTimeout
분석 완료를 30초 안에 확인하지 못함 (측정 실패 아님)
재분석 (30xxx)
Code
이름
설명
30000
reanalyzeFailed
재분석 실패
30400
reanalyzeBadRequest
Invalid start_time/end_time
30401
reanalyzeUnauthorized
Reanalyse unauthorized
30403
reanalyzeForbidden
The customer is not allowed to reanalyse the session
30404
reanalyzeNotFound
Sleep session not found
30409
reanalyzeConflict
Reanalysis is already in progress
30410
reanalyzeGone
The data retention period has expired
30422
reanalyzeUnprocessable
The session is still being tracked
30500
reanalyzeServerError
Reanalyse server error
분석 요청 (31xxx)
Code
이름
설명
31000
analyseFailed
분석 요청 실패
31400
analyseBadRequest
잘못된 타임존
31401
analyseUnauthorized
인증 실패
31404
analyseNotFound
세션을 찾을 수 없음
31500
analyseServerError
서버 오류
리포트 (32xxx · 33xxx · 34xxx)
Code
이름
설명
32000
reportFailed
리포트 조회 실패 (인터넷 없음 포함)
32400
reportBadRequest
잘못된 사용자 ID
32401
reportUnauthorized
인증 실패
32404
reportNotFound
리포트를 찾을 수 없음
32500
reportServerError
서버 오류
33000
reportsFailed
리포트 목록 실패 (인터넷 없음 포함)
33400
reportsBadRequest
잘못된 타임존
33401
reportsUnauthorized
인증 실패
33500
reportsServerError
서버 오류
34000
averageReportFailed
평균 리포트 실패 (인터넷 없음 포함)
34400
averageReportBadRequest
기간이 너무 김
34404
averageReportNotFound
사용자를 찾을 수 없음
34500
averageReportServerError
서버 오류
📘
ODAIntegrityFail(10002) 와 sseConnectFailed(22600) 는 3.3.2 부터 보내지 않는 번호이며 deprecated 입니다.
HTTP Status code
State: COMMON, INIT, TRACKING, REPORT
Code
Type
Description
State
Handling
401
Unauthorized
Unauthorized
COMMON
Client Handling
401
Unauthorized
invalid user id
COMMON
Client Handling
403
Plan is expired
Plan is expired
COMMON
SDK Stop
403
Rate limit exceeded
Rate limit exceeded
COMMON
SDK Stop
403
Quota exceeded
Quota exceeded
COMMON
SDK Stop
400
Bad Request
Invalid callback url
TRACKING
Client Handling
400
Bad Request
[WARNING] Invalid session end time. format(YYYY-MM-DDTHH:mm:ssz), 'session_end_time' must always be greater than 'session_start_time’
TRACKING
SDK Handling
403
Forbidden
the sleep session is already closed
TRACKING
SDK Stop
404
Not Found
session does not exist.
TRACKING
Client Handling
409
Conflict
previous sleep session is not closed yet
TRACKING
SDK Stop
422
Validation Error
Invalid parameter
TRACKING
SDK Handling
422
Unprocessable Entity
Invalid parameter.
TRACKING
SDK Handling
400
Bad Request
invalid timezone
REPORT
Client Handling
400
Unprocessable Entity
The format of sleep session id {session_id} is not valid
REPORT
Client Handling
401
Unauthorized
The api key is not provided
REPORT
Client Handling
404
Not Found
Unable to find the sleep session of id {session_id}
REPORT
Client 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는 나올 확률이 낮음.