버전: 0.64.0

Sleep 관련 오류 코드

Sleep 도메인 또는 관련 API(예: /sleep/logs/day-index, /sleep/goals/target-wake-time)에서 발생할 수 있는 오류 코드입니다.

오류 응답 형식

{
  "code": 10001,
  "message": "MISSING_REQUIRED_FIELDS",
  "detail": "필수 입력 항목이 누락되었습니다",
  "metadata": {
    "fields": ["sleepQuality", "lot", "aet"],
    "context": "dns=false"
  }
}

필드	타입	설명
code	number	애플리케이션 오류 코드
message	string	개발자용 오류 코드 이름 (대문자 및 언더스코어)
detail	string	사용자에게 표시할 수 있는 친화적인 오류 메시지
errors	array	필드별 유효성 검증 오류가 있는 경우 추가 정보 제공 (선택 사항)
metadata	object	오류 관련 추가 메타데이터 (선택 사항)

노트

errors와 metadata 필드는 선택 사항이며, 오류 상황에 따라 포함되지 않을 수 있습니다.

오류 코드 체계

Sleep 관련 오류는 주로 10000번대 코드를 사용합니다.

범위	용도
10000-10019	서버 및 일반 Sleep 오류
10020-10029	사용자 입력 및 형식 관련 오류
10030-10039	권한 및 보안 관련 오류
10040-10049	리소스 조회 실패 오류
10050-10059	통계 및 분석 관련 오류
10060-10079	예약됨
10080-10089	예약됨
10090-10099	리소스 충돌 및 중복 관련 오류

서버 및 일반 Sleep 오류 (10000-10019)

HTTP 상태 코드	코드	메시지	설명
500	10000	SERVER_ERROR	서버 내부 오류가 발생했습니다
400	10001	MISSING_REQUIRED_FIELDS	필수 입력 항목이 누락되었습니다
400	10002	INVALID_PARAMETERS	잘못된 파라미터입니다
400	10003	INVALID_FORMAT	입력 형식이 유효하지 않습니다
400	10004	INVALID_TIMEZONE	유효하지 않은 시간대 ID입니다
400	10005	INVALID_SLEEP_QUALITY	수면의 질 값이 유효하지 않습니다 (1~5 범위)
400	10006	INVALID_TIME_RANGE	유효하지 않은 시간 범위입니다
400	10007	INVALID_FACTOR_ID	유효하지 않은 영향 요인 ID입니다
400	10008	TOO_MANY_CUSTOM_FACTORS	사용자 정의 요인이 너무 많습니다 (최대 10개)
400	10009	SLEEP_TIME_VALIDATION_FAILED	수면 시간 검증에 실패했습니다
400	10010	DATE_VALIDATION_FAILED	날짜 검증에 실패했습니다 (당일 일차만 생성/수정 가능)
403	10011	TREATMENT_SUSPENDED	치료 활동 일시 정지 상태에서는 수면 기록을 생성할 수 없습니다
400	10012	INVALID_DAY_INDEX	유효하지 않은 일차 값입니다
400	10013	INVALID_RTIB	유효하지 않은 rTIB 값입니다
400	10014	INVALID_TST	계산된 총 수면 시간(TST)과 제공된 값이 일치하지 않습니다
400	10015	UNEXPECTED_SLEEP_DATA	DNS=true인 경우 수면 관련 데이터를 입력할 수 없습니다
400	10016	TARGET_WAKE_TIME_CHANGE_NOT_ALLOWED	목표 기상 시각 변경이 허용되지 않습니다 (rTIB 처방일에만 가능)
400	10017	INVALID_CUSTOM_FACTORS	"없음" 선택 시 해당 카테고리의 사용자 지정 요인을 입력할 수 없습니다

사용자 입력 및 형식 관련 오류 (10020-10029)

HTTP 상태 코드	코드	메시지	설명
400	10020	CUSTOM_FACTOR_TOO_LONG	사용자 정의 요인이 너무 깁니다 (최대 100자)

권한 및 보안 관련 오류 (10030-10039)

HTTP 상태 코드	코드	메시지	설명
403	10030	INSUFFICIENT_PERMISSIONS	권한이 충분하지 않습니다

리소스 조회 실패 오류 (10040-10049)

HTTP 상태 코드	코드	메시지	설명
404	10040	SLEEP_LOG_NOT_FOUND	수면 기록을 찾을 수 없습니다
404	10041	SLEEP_GOAL_NOT_FOUND	수면 목표를 찾을 수 없습니다
404	10042	RTIB_RECOMMENDATION_NOT_FOUND	rTIB 처방을 찾을 수 없습니다
404	10043	SLEEP_GOAL_ADHERENCE_NOT_FOUND	수면 목표 달성 기록을 찾을 수 없습니다
404	10044	USER_NOT_FOUND	사용자를 찾을 수 없습니다
404	10045	TEMPORARY_SLEEP_LOG_NOT_FOUND	임시 수면 기록을 찾을 수 없습니다

통계 및 분석 관련 오류 (10050-10059)

HTTP 상태 코드	코드	메시지	설명
500	10050	STATISTICS_CALCULATION_FAILED	통계 계산에 실패했습니다
400	10051	INSUFFICIENT_DATA_FOR_STATISTICS	통계를 계산하기 위한 데이터가 충분하지 않습니다

리소스 충돌 및 중복 관련 오류 (10090-10099)

HTTP 상태 코드	코드	메시지	설명
409	10090	SLEEP_LOG_ALREADY_EXISTS	해당 날짜에 이미 수면 기록이 존재합니다
409	10091	SLEEP_GOAL_ALREADY_EXISTS	해당 날짜에 이미 수면 목표가 존재합니다
429	10092	RATE_LIMIT_EXCEEDED	요청 횟수가 제한을 초과했습니다
500	10099	UNKNOWN_SLEEP_ERROR	알 수 없는 수면 도메인 오류가 발생했습니다

오류 처리 가이드

수면 기록 생성/수정 오류 처리

필수 필드 누락(10001): DNS 상태에 따른 필수 필드 목록을 사용자에게 안내합니다.

{
  "code": 10001,
  "message": "MISSING_REQUIRED_FIELDS",
  "detail": "잠을 잤을 경우 필수 입력 항목이 누락되었습니다.",
  "metadata": {
    "fields": ["sleepQuality", "lot", "aet"],
    "context": "dns=false"
  }
}

시간 검증 실패(10009): 구체적인 시간 제약사항을 사용자에게 안내합니다.

{
  "code": 10009,
  "message": "SLEEP_TIME_VALIDATION_FAILED",
  "detail": "LOT는 18:00 이후여야 하고, 시간 값은 5분 단위여야 하며, AET는 LOT보다 이후여야 합니다.",
  "metadata": {
    "lot": "2024-05-10T16:30:00.000Z",
    "aet": "2024-05-11T06:00:00.000Z"
  }
}

TST 불일치(10014): 계산된 값과 제공된 값의 차이를 명시합니다.

{
  "code": 10014,
  "message": "INVALID_TST",
  "detail": "계산된 총 수면 시간(TST)과 제공된 값이 일치하지 않습니다.",
  "metadata": {
    "calculated": 450,
    "provided": 480
  }
}

DNS(Did Not Sleep) 관련 오류 처리

UNEXPECTED_SLEEP_DATA (10015) 오류 발생 시:

{
  "code": 10015,
  "message": "UNEXPECTED_SLEEP_DATA",
  "detail": "DNS=true인 경우 수면 관련 데이터(lot, aet, solMinutes, wasoMinutes, tstMinutes)를 입력할 수 없습니다.",
  "metadata": {
    "unexpectedFields": ["lot", "aet", "sleepQuality"]
  }
}

클라이언트는 DNS=true 상태에서는 수면 관련 필드를 입력받지 않도록 UI를 조정해야 합니다.

치료 활동 제약 관련 오류 처리

치료 일시 정지(10011): 사용자에게 치료가 일시 정지된 상태임을 알리고, 정지 해제 방법을 안내합니다.
날짜 제약 위반(10010): 당일 일차에만 수면 기록 생성/수정이 가능함을 안내합니다.

리소스 충돌 오류 처리

SLEEP_LOG_ALREADY_EXISTS (10090) 오류 발생 시:

{
  "code": 10090,
  "message": "SLEEP_LOG_ALREADY_EXISTS",
  "detail": "해당 날짜에 이미 수면 기록이 존재합니다.",
  "metadata": {
    "dayIndex": 7,
    "existingId": "sl_12345"
  }
}

클라이언트는 기존 기록을 수정하거나 덮어쓸지 사용자에게 선택하도록 안내할 수 있습니다.

속도 제한 처리

RATE_LIMIT_EXCEEDED (10092) 오류 발생 시:

{
  "code": 10092,
  "message": "RATE_LIMIT_EXCEEDED",
  "detail": "요청 횟수가 제한을 초과했습니다",
  "metadata": {
    "remainingLockoutSeconds": 300,
    "maxAttemptsAllowed": 10
  }
}

클라이언트는 metadata.remainingLockoutSeconds 값을 확인하여 사용자에게 남은 대기 시간을 표시하고, 적절한 재시도 로직을 구현해야 합니다.

사용자 입력 형식 검증

수면의 질 범위 오류(10005):

1~5 범위 외의 값 입력 시 발생
UI에서 유효한 범위를 명확히 표시해야 함

영향 요인 관련 오류:

INVALID_FACTOR_ID (10007): 존재하지 않는 영향 요인 ID 참조
TOO_MANY_CUSTOM_FACTORS (10008): 사용자 정의 요인 10개 초과
CUSTOM_FACTOR_TOO_LONG (10020): 사용자 정의 요인 100자 초과

rTIB 관련 오류 처리

TARGET_WAKE_TIME_CHANGE_NOT_ALLOWED (10016): rTIB 처방일이 아닌 날에 목표 기상 시각 변경 시도
RTIB_RECOMMENDATION_NOT_FOUND (10042): 해당 일차의 rTIB 처방이 없는 경우

통계 및 분석 오류 처리

INSUFFICIENT_DATA_FOR_STATISTICS (10051) 오류 발생 시:

사용자에게 충분한 수면 기록이 축적될 때까지 기다리도록 안내
필요한 최소 데이터 개수(예: 4개 이상의 유효한 기록)를 명시

특별 고려사항

시간 관련 검증

Sleep 도메인에서는 다음과 같은 시간 관련 제약사항이 있습니다:

5분 단위 입력: 모든 시간 입력은 5분 단위로만 허용
LOT 시간 제약: 18:00 이후여야 함
AET > LOT: 일어난 시각은 잠자리에 든 시각보다 이후여야 함
당일 일차 제약: 현재 진행 중인 일차에만 생성/수정 가능

데이터 일관성

TST(총 수면 시간) 계산값과 사용자 입력값의 일치성 검증
DNS 상태에 따른 필수/금지 필드 검증
치료 주기와 일차 정보의 일관성 유지

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-05-23	dalia@weltcorp.com	최초 작성

오류 응답 형식​

오류 코드 체계​

서버 및 일반 Sleep 오류 (10000-10019)​

사용자 입력 및 형식 관련 오류 (10020-10029)​

권한 및 보안 관련 오류 (10030-10039)​

리소스 조회 실패 오류 (10040-10049)​

통계 및 분석 관련 오류 (10050-10059)​

리소스 충돌 및 중복 관련 오류 (10090-10099)​

오류 처리 가이드​

수면 기록 생성/수정 오류 처리​

DNS(Did Not Sleep) 관련 오류 처리​

치료 활동 제약 관련 오류 처리​

리소스 충돌 오류 처리​

속도 제한 처리​

사용자 입력 형식 검증​

rTIB 관련 오류 처리​

통계 및 분석 오류 처리​

특별 고려사항​

시간 관련 검증​

데이터 일관성​

변경 이력​