버전: 0.68.0

Auth 도메인 오류 코드

이 문서는 Auth 도메인의 API에서 발생할 수 있는 오류 코드와 메시지에 대한 종합적인 참조를 제공합니다. 각 API 레퍼런스 문서에도 관련 오류 코드가 포함되어 있으므로, 특정 API 사용 시에는 해당 문서를 확인하는 것이 좋습니다.

오류 응답 형식

{
  "code": 2000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류가 발생했습니다",
  "metadata": {
    "exampleKey": "exampleValue"
  }
}

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

노트

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

오류 코드 체계

API 오류 코드는 도메인별로 고유한 숫자 범위를 사용하여 관리됩니다. 예를 들어, Auth 도메인은 주로 2000번대 오류 코드를 사용하며, 다른 도메인은 별도의 코드 범위를 가집니다 (예: Access Code 관련 오류는 3000번대).

이 문서는 주로 **Auth 도메인(2000번대)**에서 발생하는 오류 코드에 대해 설명합니다. 다른 도메인 관련 오류 코드는 해당 도메인의 문서를 참조하거나 아래 링크를 확인하세요:

Access Code 관련 오류 코드

Auth 도메인 오류 코드 범위

범위	용도
2000-2010	기본 인증 오류 (서버 오류 포함)
2011-2019	디바이스 및 앱 인증 관련 오류
2020-2039	사용자 인증 관련 오류
2040-2049	속도 제한 및 보안 관련 오류
2050-2059	토큰 관련 오류
2060-2069	권한 관련 오류
2070-2079	Auth 도메인의 Access Code 관련 오류
2080-2089	약관 관련 오류
2090-2099	기타 Auth 도메인 오류 (비밀번호 관련)

노트

이전에는 Access Code 관련 오류가 2070-2079 범위에 포함되었으나, 도메인 분리 원칙에 따라 모든 Access Code 관련 오류는 이제 Access Code 도메인(3000번대)에서 처리됩니다. 자세한 내용은 Access Code 오류 코드를 참조하세요.

기본 인증 오류 코드 (2000-2010)

HTTP 상태 코드	코드	메시지	설명
500	2000	SERVER_ERROR	서버 내부 오류
401	2001	APP_TOKEN_EXPIRED	토큰이 만료되었습니다
401	2002	INVALID_APP_TOKEN	토큰이 유효하지 않습니다 ⚠️ Deprecated
401	2003	REFRESH_TOKEN_EXPIRED	리프레시 토큰이 만료되었습니다
403	2004	ACCOUNT_LOCKED	계정이 잠겨 있습니다
403	2005	PASSWORD_CHANGE_REQUIRED	비밀번호 변경이 필요합니다
401	2006	INVALID_MFA_CODE	다중 인증 코드가 유효하지 않습니다
403	2007	MFA_REQUIRED	다중 인증이 필요합니다
403	2008	EMAIL_NOT_VERIFIED	이메일이 인증되지 않았습니다
403	2009	ACCOUNT_INACTIVE	계정이 비활성화 상태입니다
401	2010	INVALID_CREDENTIALS	이메일 또는 비밀번호가 올바르지 않습니다

서버 오류 처리 가이드

서버 오류(2000)는 백엔드 시스템에 문제가 있을 때 발생합니다. 클라이언트 애플리케이션에서는 다음과 같이 처리하는 것이 좋습니다:

지수 백오프 재시도: 서버 오류 발생 시 즉시 재시도하지 말고, 지수적으로 증가하는 대기 시간 후 재시도
최대 재시도 횟수 설정: 일정 횟수(예: 3-5회) 이상 재시도 실패 시 사용자에게 알림
오프라인 모드 전환: 가능한 경우 일시적으로 오프라인 모드로 전환하여 기본 기능 제공
로깅 및 모니터링: 모든 서버 오류를 로깅하고 애널리틱스에 보고하여 패턴 파악

디바이스 및 앱 인증 오류 코드 (2011-2019)

HTTP 상태 코드	코드	메시지	설명
400	2011	INVALID_DEVICE_ID	디바이스 ID가 유효하지 않습니다
401	2012	CHALLENGE_VERIFICATION_FAILED	챌린지 검증에 실패했습니다
403	2013	DEVICE_BLACKLISTED	디바이스가 블랙리스트에 등록되어 있습니다
400	2014	VERIFICATION_CODE_EXPIRED	인증 코드가 만료되었습니다
400	2016	DEVICE_HASH_MISMATCH	디바이스 ID 해시가 계산된 값과 일치하지 않습니다
400	2017	INVALID_VERIFICATION_CODE	인증 코드가 올바르지 않습니다
429	2018	VERIFICATION_ATTEMPTS_EXCEEDED	인증 코드 확인 시도 횟수를 초과했습니다
404	2019	DEVICE_NOT_FOUND	디바이스 정보를 찾을 수 없습니다

노트

이전에 사용되던 INVALID_APP_TOKEN(2015) 오류 코드는 모든 토큰 검증 오류를 일관되게 처리하기 위해 INVALID_APP_TOKEN(2002)로 통합되었습니다. 자세한 내용은 아래 토큰 관련 오류 코드 섹션을 참조하세요.

앱 인증 오류 발생 원인 및 해결 방법

INVALID_DEVICE_ID (2011)

원인: 디바이스 ID가 없거나, 형식이 올바르지 않거나, 지원되지 않는 형식입니다.
해결 방법:
- 필수 필드 확인: deviceInfo 객체에 uuid, platform, version 필드가 모두 포함되어 있는지 확인하세요.
- 해시 형식 검증: 해시가 64자리 16진수 문자열(SHA-256)인지 확인하세요.
- 해시 계산 일치: 디바이스 정보를 JSON으로 직렬화한 후 정확히 SHA-256 해싱하여 생성한 해시가 서버에서 계산한 값과 일치하는지 확인하세요.
- 디바이스 정보 일관성: 서버와 클라이언트 간 디바이스 정보 형식과 구조가 일치하는지 확인하세요.
- 백업 식별자 구현: 디바이스 UUID를 앱 설치 시 생성하여 안전한 저장소에 보관하고, 앱 재설치 시에도 일관된 식별자를 사용하세요.

CHALLENGE_VERIFICATION_FAILED (2012)

원인: 암호화된 챌린지 응답이 서버의 예상 값과 일치하지 않습니다.
해결 방법:
- 앱 시크릿이 올바르게 저장되어 있는지 확인
- 서버 타임스탬프와 로컬 시간 차이가 너무 크지 않은지 확인
- 암호화 알고리즘 구현이 정확한지 확인

DEVICE_BLACKLISTED (2013)

원인: 디바이스가 보안상의 이유로 블랙리스트에 등록되었습니다.
해결 방법:
- 사용자에게 관리자나 지원팀에 문의하도록 안내
- 루팅/탈옥 감지 부분 확인
- 불법 앱 설치 여부 확인

VERIFICATION_CODE_EXPIRED (2014)

원인: 인증 코드가 만료되었습니다.
해결 방법:
- 새로운 인증 코드 요청
- 코드 유효 시간 안내

DEVICE_HASH_MISMATCH (2016)

원인: 요청에 포함된 디바이스 ID 해시가 서버에서 계산한 값과 일치하지 않습니다.
해결 방법:
- 해시 생성 알고리즘 확인
- 디바이스 정보 JSON 직렬화 순서 확인
- 시크릿 값이 올바르게 적용되었는지 확인

INVALID_VERIFICATION_CODE (2017)

원인: 입력된 인증 코드가 올바르지 않습니다.
해결 방법:
- 사용자에게 코드를 다시 확인하도록 안내
- 코드 입력 필드 강조 표시

VERIFICATION_ATTEMPTS_EXCEEDED (2018)

원인: 인증 코드 확인 시도 횟수를 초과했습니다.
해결 방법:
- 남은 잠금 시간 표시
- 새 코드 요청 옵션 제공

DEVICE_NOT_FOUND (2019)

원인: 요청한 디바이스 정보를 찾을 수 없습니다.
해결 방법:
- 디바이스 등록 프로세스 재시작
- 앱 데이터 초기화 고려

사용자 인증 오류 코드 (2020-2039)

HTTP 상태 코드	코드	메시지	설명
400	2021	WEAK_PASSWORD	비밀번호가 보안 요구사항을 충족하지 않습니다
409	2022	PASSWORD_HISTORY_MATCH	최근에 사용한 비밀번호입니다
400	2023	INVALID_EMAIL_FORMAT	유효한 이메일 주소를 입력해주세요
409	2024	DUPLICATE_EMAIL	이미 가입된 이메일 주소입니다
404	2025	EMAIL_NOT_FOUND	존재하지 않는 이메일입니다
409	2026	EMAIL_VERIFICATION_ALREADY_COMPLETED	이미 인증이 완료된 코드입니다
422	2027	UNREGISTERED_EMAIL	가입되지 않은 이메일입니다
400	2028	REGISTRATION_VALIDATION_FAILED	가입 정보 검증에 실패했습니다

사용자 인증 오류 처리 가이드

회원가입 오류

DUPLICATE_EMAIL (2024): 회원가입 시 이미 등록된 이메일 사용
- 사용자에게 로그인 화면으로 이동하거나 비밀번호 재설정 옵션을 제공
- 소셜 로그인 선택지 제공
EMAIL_NOT_FOUND (2025): 존재하지 않는 이메일 조회
- 회원가입 화면으로 리다이렉트
- 올바른 이메일 주소 입력 유도
UNREGISTERED_EMAIL (2027): 가입되지 않은 이메일로 로그인 시도
- 회원가입 프로세스 안내
- 이메일 주소 재확인 요청
WEAK_PASSWORD (2021): 비밀번호가 보안 요구사항 미충족
- 구체적인 비밀번호 요구사항 안내 (최소 8자, 특수문자, 대문자 포함 등)
- 비밀번호 강도 측정기 제공
PASSWORD_HISTORY_MATCH (2022): 최근에 사용한 비밀번호 재사용
- 새로운 비밀번호 작성 유도
- 이전에 사용하지 않은 비밀번호 요청
INVALID_EMAIL_FORMAT (2023): 이메일 형식이 유효하지 않음
- 올바른 이메일 형식 안내
- 입력 필드에 즉각적인 유효성 검사 적용
EMAIL_VERIFICATION_ALREADY_COMPLETED (2026): 이미 완료된 이메일 인증 재시도
- 로그인 화면으로 리다이렉트
- 이미 인증 완료되었음을 안내
REGISTRATION_VALIDATION_FAILED (2028): 가입 정보 검증 실패
- 입력된 정보의 형식 및 유효성 검사 결과 안내
- 구체적인 필드별 오류 메시지 제공
- 잘못된 입력 필드 강조 표시

보안 및 속도 제한 오류 코드 (2040-2049)

HTTP 상태 코드	코드	메시지	설명
429	2040	RATE_LIMIT_EXCEEDED	요청 횟수가 제한을 초과했습니다
403	2041	SUSPICIOUS_ACTIVITY	의심스러운 활동이 감지되었습니다

속도 제한 처리 모범 사례

지수 백오프: 재시도 시 시간 간격을 점진적으로 늘림
Retry-After 헤더 활용: 응답에 포함된 대기 시간 준수
사용자 피드백: 대기 시간이 긴 경우 진행 상태 표시
요청 우선순위 지정: 중요한 요청과 덜 중요한 요청을 구분하여 처리

의심스러운 활동 대응 가이드

사용자에게 보안 확인 절차 안내 (이메일 확인, 2FA 등)
디바이스 인증 정보 재설정
비정상 활동 로그 수집 및 보고
보안 담당자에게 알림

토큰 관련 오류 코드 (2050-2059)

HTTP 상태 코드	코드	메시지	설명
400	2050	INVALID_NONCE	제공된 nonce가 유효하지 않거나 이미 사용되었습니다
401	2051	INVALID_TOKEN	토큰이 유효하지 않습니다
403	2052	TOKEN_REFRESH_FORBIDDEN	토큰 갱신이 금지되었습니다
401	2053	TOKEN_REVOKED	토큰이 취소되었습니다

노트

이전에 사용되던 INVALID_APP_TOKEN(2002) 오류 코드는 deprecated되었으며, 모든 토큰 검증 오류는 이제 INVALID_TOKEN(2051)을 사용합니다. 이는 모든 유형의 토큰(액세스 토큰, 앱 토큰 등) 검증 오류를 일관되게 처리하기 위한 조치입니다.

토큰 오류 자동 복구 매커니즘

액세스 토큰 만료 감지: 401 상태 코드와 APP_TOKEN_EXPIRED 오류 코드 확인
리프레시 토큰 사용: 자동으로 리프레시 토큰을 사용하여 새 액세스 토큰 요청
원본 요청 재시도: 새 액세스 토큰으로 원래 요청 재시도
리프레시 토큰 오류 처리: 리프레시 토큰도 문제가 있는 경우 로그인 화면으로 리다이렉트

// 토큰 자동 복구 매커니즘 예시 코드
async function executeRequestWithTokenRecovery(request) {
  try {
    return await executeRequest(request);
  } catch (error) {
    if (error.status === 401 && error.code === 2001) {
      // APP_TOKEN_EXPIRED
      try {
        await refreshAccessToken();
        return await executeRequest(request); // 원본 요청 재시도
      } catch (refreshError) {
        // 리프레시 토큰도 유효하지 않은 경우
        if (refreshError.status === 401 && (refreshError.code === 2003 || refreshError.code === 2051)) {
          // REFRESH_TOKEN_EXPIRED 또는 INVALID_TOKEN
          redirectToLogin();
        }
        throw refreshError;
      }
    }
    throw error;
  }
}

권한 관련 오류 코드 (2060-2069)

HTTP 상태 코드	코드	메시지	설명
403	2060	PERMISSION_DENIED	요청한 작업에 대한 권한이 없습니다
403	2061	INSUFFICIENT_ROLE	요청한 작업을 수행하기 위한 역할이 부족합니다

권한 오류 처리 UI/UX 가이드

명확한 메시지 제공: 필요한 권한과 사용자의 현재 권한 상태 설명
권한 획득 경로 제시: 필요한 권한을 얻기 위한 방법 안내
대체 기능 제안: 현재 권한으로 이용 가능한 대체 기능 제시
UI 요소 비활성화: 권한이 없는 작업은 UI에서 비활성화하거나 숨기기

약관 관련 오류 코드 (2080-2089)

HTTP 상태 코드	코드	메시지	설명
412	2080	REQUIRED_AGREEMENTS_NOT_AGREED	필수 약관에 동의하지 않았습니다

약관 오류 처리 가이드

REQUIRED_AGREEMENTS_NOT_AGREED (2080): 필수 약관 미동의
- 약관 동의 화면으로 리다이렉트
- 필수 약관과 선택 약관을 명확히 구분하여 표시
- 약관 내용을 쉽게 확인할 수 있는 링크 제공
- 동의 후 원래 진행하던 프로세스로 복귀

Access Code 관련 오류 코드 (2070-2079)

HTTP 상태 코드	코드	메시지	설명
400	2070	INVALID_ACCESS_CODE	유효하지 않은 Access Code입니다
409	2071	ACCESS_CODE_ALREADY_USED	이미 사용된 Access Code입니다
400	2072	ACCESS_CODE_EXPIRED	만료된 Access Code입니다

노트

이러한 오류 코드는 Auth 도메인에서 Access Code를 처리할 때 사용됩니다. 독립적인 Access Code 도메인(3000번대)에 대한 자세한 내용은 Access Code 오류 코드를 참조하세요.

기타 Auth 도메인 오류 코드 (2090-2099)

HTTP 상태 코드	코드	메시지	설명
400	2090	PASSWORD_ALREADY_USED	현재 비밀번호 해시와 동일합니다
400	2091	INVALID_PASSWORD	비밀번호가 올바르지 않습니다
400	2092	PASSWORD_NOT_VERIFIED	비밀번호 인증이 완료되지 않았습니다
500	2099	UNKNOWN_AUTH_ERROR	알 수 없는 인증 오류가 발생했습니다

비밀번호 관련 오류 처리 가이드

비밀번호 변경 오류

PASSWORD_ALREADY_USED (2090): 현재 비밀번호해시와 동일한 비밀번호해시로 변경 시도
- 사용자에게 새로운 비밀번호 입력 요청
- "현재 비밀번호와 다른 비밀번호를 입력해주세요" 메시지 표시
INVALID_PASSWORD (2091): 잘못된 현재 비밀번호 입력
- 현재 비밀번호 재입력 요청
- 비밀번호 재설정 옵션 제공
- 입력 필드 강조 표시
PASSWORD_NOT_VERIFIED (2092): 비밀번호 인증 단계 미완료
- 비밀번호 인증 단계로 리다이렉트
- 진행 상태 표시
- 검증 완료 후 원래 작업 재개

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-04-15	bok@weltcorp.com	최초 작성
0.2.0	2025-05-01	bok@weltcorp.com	토큰 오류 코드 통합(INVALID_APP_TOKEN), Access Code 오류 코드 이동 반영
0.3.0	2025-05-02	bok@weltcorp.com	누락된 에러 코드 추가 (INVALID_EMAIL_FORMAT, INVALID_NONCE, EMAIL_VERIFICATION_ALREADY_COMPLETED 등)
0.4.0	2025-05-15	bok@weltcorp.com	REGISTRATION_VALIDATION_FAILED(2028) 오류 코드 추가
1.0.0	2025-09-18	AI Assistant	코드 기반 전면 업데이트: 에러 코드 범위 재정리, 새로운 비밀번호 관련 오류(2090-2092) 추가, 약관 관련 오류(2080) 추가, INVALID_APP_TOKEN deprecated 반영, 코드와 문서 일관성 확보

오류 응답 형식​

오류 코드 체계​

Auth 도메인 오류 코드 범위​

기본 인증 오류 코드 (2000-2010)​

서버 오류 처리 가이드​

디바이스 및 앱 인증 오류 코드 (2011-2019)​

앱 인증 오류 발생 원인 및 해결 방법​

INVALID_DEVICE_ID (2011)​

CHALLENGE_VERIFICATION_FAILED (2012)​

DEVICE_BLACKLISTED (2013)​

VERIFICATION_CODE_EXPIRED (2014)​

DEVICE_HASH_MISMATCH (2016)​

INVALID_VERIFICATION_CODE (2017)​

VERIFICATION_ATTEMPTS_EXCEEDED (2018)​

DEVICE_NOT_FOUND (2019)​

사용자 인증 오류 코드 (2020-2039)​

사용자 인증 오류 처리 가이드​

회원가입 오류​

보안 및 속도 제한 오류 코드 (2040-2049)​

속도 제한 처리 모범 사례​

의심스러운 활동 대응 가이드​

토큰 관련 오류 코드 (2050-2059)​

토큰 오류 자동 복구 매커니즘​

권한 관련 오류 코드 (2060-2069)​

권한 오류 처리 UI/UX 가이드​

약관 관련 오류 코드 (2080-2089)​

약관 오류 처리 가이드​

Access Code 관련 오류 코드 (2070-2079)​

기타 Auth 도메인 오류 코드 (2090-2099)​

비밀번호 관련 오류 처리 가이드​

비밀번호 변경 오류​

변경 이력​