Access Code 관련 오류 코드
Access Code 도메인 또는 관련 API(예: /auth/access-code/validate)에서 발생할 수 있는 오류 코드입니다.
오류 응답 형식
{
"code": 3001,
"message": "INVALID_CODE",
"detail": "유효하지 않은 Access Code입니다",
"metadata": {
"attemptCount": 3
}
}
| 필드 | 타입 | 설명 |
|---|---|---|
| code | number | 애플리케이션 오류 코드 |
| message | string | 개발자용 오류 코드 이름 (대문자 및 언더스코어) |
| detail | string | 사용자에게 표시할 수 있는 친화적인 오류 메시지 |
| errors | array | 필드별 유효성 검증 오류가 있는 경우 추가 정보 제공 (선택 사항) |
| metadata | object | 오류 관련 추가 메타데이터 (선택 사항) |
노트
errors와 metadata 필드는 선택 사항이며, 오류 상황에 따라 포함되지 않을 수 있습니다.
오류 코드 체계
Access Code 관련 오류는 주로 3000번대 코드를 사용합니다.
| 범위 | 용도 |
|---|---|
| 3000-3009 | 서버 및 일반 Access Code 오류 |
| 3010-3019 | 권한 관리 관련 오류 |
| 3020-3029 | TimeMachine 통합 관련 오류 |
| 3030-3039 | 배치 처리 관련 오류 |
| 3040-3049 | 발급 출처 및 속도 제한/보안 관련 오류 |
| 3050-3059 | 동의 관리 관련 오류 |
| 3060-3069 | 개인정보 관리 관련 오류 |
| 3070-3099 | 기타 Access Code 도메인 오류 |
일반 Access Code 오류 (3000-3009)
참고: 이전에는 Auth 도메인에서 Access Code 관련 오류를 2070-2079 범위로 처리했으나, 도메인 분리 원칙에 따라 이제는 모든 Access Code 관련 오류는 Access Code 도메인(3000번대)에서 처리합니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 500 | 3000 | SERVER_ERROR | 서버 내부 오류가 발생했습니다 |
| 400 | 3001 | INVALID_CODE | 제공된 Access Code가 존재하지 않거나 형식이 잘못되었습니다 |
| 409 | 3002 | CODE_ALREADY_USED | 제공된 Access Code가 이미 다른 사용자에 의해 사용되었습니다 |
| 400 | 3003 | CODE_EXPIRED | 제공된 Access Code의 유효 기간이 만료되었습니다 |
| 409 | 3004 | DUPLICATE_CODE | 생성하려는 Access Code가 이미 존재합니다 |
| 404 | 3005 | CODE_NOT_FOUND | 해당 ID의 Access Code를 찾을 수 없습니다 |
| 400 | 3006 | CODE_REVOKED | Access Code가 관리자에 의해 취소되었습니다 |
| 403 | 3007 | CODE_BLOCKED | Access Code가 보안상의 이유로 차단되었습니다 |
| 400 | 3008 | CODE_VALIDATION_FAILED | Access Code 검증 과정에서 오류가 발생했습니다 |
| 400 | 3009 | ACCESS_CODE_NOT_VALIDATED | 회원가입 등 후속 프로세스 진행 시 Access Code 검증이 완료되지 않았습니다 |
권한 관리 관련 오류 (3010-3019)
Access Code와 연결된 권한 및 리소스 접근 제어 관련 오류입니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 400 | 3010 | PERMISSION_VALIDATION_FAILED | Access Code에 연결된 권한 검증에 실패했습니다 |
| 400 | 3011 | INVALID_PERMISSION_ACTION | 요청한 권한 작업이 유효하지 않습니다 |
| 500 | 3012 | PERMISSION_ASSIGNMENT_FAILED | 권한 할당 과정에서 오류가 발생했습니다 |
| 500 | 3013 | PERMISSION_REVOCATION_FAILED | 권한 취소 과정에서 오류가 발생했습니다 |
| 403 | 3014 | SCOPE_NOT_ALLOWED | 요청한 범위(scope)에 대한 접근 권한이 없습니다 |
| 404 | 3015 | PERMISSION_NOT_FOUND | 요청한 권한을 찾을 수 없습니다 |
TimeMachine 통합 관련 오류 (3020-3029)
가상 시간 설정 및 타임머신 기능 관련 오류를 처리합니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 400 | 3020 | INVALID_VIRTUAL_TIME_SETTINGS | 가상 시간 설정 값이 유효하지 않습니다 |
| 500 | 3021 | TIME_MACHINE_INTEGRATION_FAILED | 타임머신 서비스 연동 중 오류가 발생했습니다 |
| 400 | 3022 | VIRTUAL_TIME_STARTDATE_REQUIRED | 가상 시간 설정에 시작 날짜가 필요합니다 |
| 400 | 3023 | VIRTUAL_TIME_TOO_FAR_FUTURE | 요청한 가상 시간이 허용된 미래 범위를 초과합니다 |
| 400 | 3024 | VIRTUAL_TIME_TOO_FAR_PAST | 요청한 가상 시간이 허용된 과거 범위를 초과합니다 |
배치 처리 관련 오류 (3030-3039)
다수의 Access Code를 생성하고 관리하는 배치 작업 관련 오류입니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 404 | 3030 | BATCH_JOB_NOT_FOUND | 요청한 배치 작업을 찾을 수 없습니다 |
| 500 | 3031 | BATCH_PROCESSING_ERROR | 배치 작업 처리 중 오류가 발생했습니다 |
| 400 | 3032 | INVALID_BATCH_PARAMETERS | 배치 작업 파라미터가 유효하지 않습니다 |
| 400 | 3033 | BATCH_SIZE_LIMIT_EXCEEDED | 요청한 배치 크기가 허용 한도를 초과했습니다 |
발급 출처 및 보안 관련 오류 (3040-3049)
Access Code 발급 출처의 유효성, 연동 및 속도 제한 관련 오류입니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 400 | 3040 | INVALID_ISSUE_SOURCE_TYPE | Access Code 발급 출처 타입이 유효하지 않습니다 |
| 400 | 3041 | INVALID_ISSUE_SOURCE_METADATA | 발급 출처 메타데이터가 유효하지 않습니다 |
| 400 | 3042 | ISSUE_SOURCE_VALIDATION_FAILED | 발급 출처 검증에 실패했습니다 |
| 429 | 3045 | RATE_LIMIT_EXCEEDED | 요청 횟수가 제한을 초과했습니다 |
동의 관리 관련 오류 (3050-3059)
사용자 동의 상태 검증 및 관리 관련 오류입니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 404 | 3050 | CONSENT_NOT_FOUND | 요청한 동의 정보를 찾을 수 없습니다 |
| 500 | 3051 | CONSENT_UPDATE_FAILED | 동의 정보 업데이트 중 오류가 발생했습니다 |
| 400 | 3052 | REQUIRED_CONSENT_MISSING | 필수 동의 항목이 누락되었습니다 |
개인정보 관리 관련 오류 (3060-3069)
GDPR 및 개인정보 보호법 관련 기능의 오류를 처리합니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 404 | 3060 | PERSONAL_DATA_NOT_FOUND | 요청한 개인정보를 찾을 수 없습니다 |
| 403 | 3061 | PERSONAL_DATA_ACCESS_DENIED | 개인정보 접근이 거부되었습니다 |
| 500 | 3062 | PERSONAL_DATA_OPERATION_FAILED | 개인정보 처리 작업 중 오류가 발생했습니다 |
기타 오류 (3070-3099)
위 범주에 속하지 않는 시스템 및 구성 관련 오류입니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 500 | 3070 | CONFIGURATION_ERROR | Access Code 시스템 구성 오류가 발생했습니다 |
오류 처리 가이드
일반 코드 검증 오류 처리
- 유효하지 않은 코드(3001): 사용자에게 코드를 다시 확인하고 입력하도록 안내합니다.
- 이미 사용된 코드(3002): 사용자에게 해당 코드가 이미 사용되었음을 알리고, 필요한 경우 새로운 코드를 발급받도록 안내합니다.
- 만료된 코드(3003): 사용자에게 코드 유효 기간이 만료되었음을 알리고, 필요한 경우 새로운 코드를 발급받도록 안내합니다.
- 차단된 코드(3007): 사용자에게 보안상의 이유로 코드가 차단되었음을 알리고, 관리자나 지원팀에 문의하도록 안내합니다.
속도 제한 처리
RATE_LIMIT_EXCEEDED (3045) 오류 발생 시:
{
"code": 3045,
"message": "RATE_LIMIT_EXCEEDED",
"detail": "요청 횟수가 제한을 초과했습니다",
"metadata": {
"remainingLockoutSeconds": 300,
"maxAttemptsAllowed": 5
}
}
클라이언트는 metadata.remainingLockoutSeconds 값을 확인하여 사용자에게 남은 대기 시간을 표시하고, Retry-After 헤더 값을 준수하여 재시도 로직을 구현해야 합니다.
배치 작업 오류 처리
배치 작업 관련 오류(3030-3033)는 주로 관리자 도구나 백엔드 시스템에서 발생합니다. 이러한 오류가 발생할 경우:
- 각 배치 작업의 고유 ID와 오류 세부 정보를 로깅합니다.
- 부분적으로 성공한 작업의 결과를 사용자에게 제공합니다.
- 실패한 작업에 대한 재시도 메커니즘을 구현합니다.
타임머신 기능 사용 시 주의사항
가상 시간 설정 관련 오류(3020-3024)가 발생할 경우:
- 유효한 날짜 범위에 대한 가이드라인을 제공합니다(예: "현재 시점으로부터 최대 30일 후까지만 설정 가능").
- 날짜 선택 UI에 허용 범위를 명확히 표시합니다.
- 시간대(timezone) 차이로 인한 오류가 발생하지 않도록 UTC 기준으로 날짜/시간을 처리합니다.
변경 이력
| 버전 | 날짜 | 작성자 | 변경 내용 |
|---|---|---|---|
| 0.1.0 | 2025-03-10 | bok@weltcorp.com | 최초 작성 |
| 0.2.0 | 2025-04-20 | bok@weltcorp.com | 오류 코드 체계 개편, Auth 도메인에서 분리된 Access Code 관련 오류 코드 추가 |
| 0.3.0 | 2025-05-15 | bok@weltcorp.com | access-code-error-codes.enum.ts에 정의된 모든 오류 코드 반영 및 설명 추가 |