일반/시스템 오류 코드
일반/시스템 오류는 특정 도메인에 국한되지 않고 애플리케이션 전반에서 발생할 수 있는 오류 코드입니다. 이 오류 코드들은 libs/core/error-handling/src/lib/enums/error-code.enum.ts 파일에 정의되어 있습니다.
오류 응답 형식
기본 오류 응답
{
"code": 1002,
"message": "NOT_FOUND",
"detail": "요청한 리소스를 찾을 수 없습니다"
}
Validation 오류 응답 (상세 필드 정보 포함)
{
"code": 1001,
"message": "VALIDATION_ERROR",
"detail": "입력 값이 유효하지 않습니다",
"errors": [
{
"field": "email",
"message": "must be an email"
},
{
"field": "content",
"message": "Invalid WCS URI format. Expected: wcs://[language]/[version]/[path]"
}
]
}
메타데이터를 포함한 오류 응답
{
"code": 1006,
"message": "CONFLICT",
"detail": "리소스 상태 충돌이 발생했습니다",
"metadata": {
"requestId": "req-12345",
"conflictingResource": "user_email"
}
}
응답 필드 상세
| 필드 | 타입 | 설명 |
|---|---|---|
| code | number | 애플리케이션 오류 코드 |
| message | string | 개발자용 오류 코드 이름 (대문자 및 언더스코어) |
| detail | string | 사용자에게 표시할 수 있는 친화적인 오류 메시지 |
| errors | array | 필드별 유효성 검증 오류가 있는 경우 추가 정보 제공 (선택 사항) |
| metadata | object | 오류 관련 추가 메타데이터 (선택 사항) |
ValidationErrorDetail 타입 정의
Validation 오류 시 errors 배열에 포함되는 각 항목의 구조:
interface ValidationErrorDetail {
field: string; // 오류가 발생한 필드명 (nested.field, items[0].name 등 지원)
message: string; // 해당 필드의 구체적인 오류 메시지
}
지원하는 필드명 형식:
- 기본 필드:
"email","name","accessCode" - 중첩 필드:
"user.profile.email","address.zipCode" - 배열 인덱스:
"items[0].name","users[2].email"
노트
errors와 metadata 필드는 선택 사항이며, 오류 상황에 따라 포함되지 않을 수 있습니다.
errors 배열은 주로 VALIDATION_ERROR (1001) 코드와 함께 사용됩니다.
오류 코드 체계
일반/시스템 오류는 주로 1000번대 코드를 사용합니다.
| 범위 | 용도 |
|---|---|
| 1000-1099 | 일반/시스템 오류 |
주요 오류 코드 상세
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 500 | 1000 | UNKNOWN_ERROR | 알 수 없는 오류가 발생했습니다 |
| 400 | 1001 | VALIDATION_ERROR | 요청 데이터 유효성 검증에 실패했습니다 |
| 404 | 1002 | NOT_FOUND | 요청한 리소스를 찾을 수 없습니다 |
| 401 | 1003 | UNAUTHORIZED | 인증되지 않은 요청입니다 |
| 403 | 1004 | FORBIDDEN | 요청한 작업에 대한 권한이 없습니다 |
| 400 | 1005 | BAD_REQUEST | 잘못된 요청입니다 |
| 409 | 1006 | CONFLICT | 리소스 상태 충돌이 발생했습니다 |
| 500 | 1007 | INTERNAL_SERVER_ERROR | 서버 내부 오류가 발생했습니다 |
| 503 | 1008 | SERVICE_UNAVAILABLE | 서비스를 일시적으로 사용할 수 없습니다 |
| 500 | 1009 | DATABASE_ERROR | 데이터베이스 오류가 발생했습니다 |
| 500 | 1010 | NETWORK_ERROR | 네트워크 오류가 발생했습니다 |
| 408 | 1011 | TIMEOUT_ERROR | 요청 처리 시간이 초과되었습니다 |
| 422 | 1012 | UNPROCESSABLE_ENTITY | 요청은 유효하나 처리할 수 없습니다 |
| 429 | 1013 | TOO_MANY_REQUESTS | 요청 횟수가 제한을 초과했습니다 |
| 429 | 1014 | RATE_LIMIT_EXCEEDED | 초당 요청 제한을 초과했습니다 |
| 429 | 1015 | QUOTA_EXCEEDED | 할당량을 초과했습니다 (일일/월간 API 호출 등) |
| 429 | 1016 | RETRY_AFTER | 재시도 대기 시간이 필요합니다 |
| 403 | 1017 | IP_BLOCKED | 과도한 요청으로 IP가 일시적으로 차단되었습니다 |
도메인별 오류 코드 체계
전체 API 오류 코드는 도메인별로 고유한 숫자 범위를 사용하여 관리됩니다:
| 범위 | 도메인 | 문서 링크 |
|---|---|---|
| 1000-1999 | 일반/시스템 | 현재 문서 |
| 2000-2999 | 인증(Auth) | Auth 도메인 오류 코드 |
| 3000-3999 | 액세스 코드(Access Code) | Access Code 오류 코드 |
| 4000-4999 | 환자 관리(Patient Management) | - |
| 5000-5999 | 임상(Clinical) | - |
일반 오류 처리 가이드
클라이언트 측 처리 권장사항
서버 오류 (500번대)
서버 오류(1000, 1007, 1008, 1009, 1010)는 다음과 같이 처리하는 것이 좋습니다:
- 지수 백오프 재시도: 즉시 재시도하지 말고, 점진적으로 증가하는 대기 시간 후 재시도
- 최대 재시도 횟수 설정: 일정 횟수(예: 3-5회) 이상 재시도 실패 시 사용자에게 알림
- 오프라인 모드 전환: 가능한 경우 일시적으로 오프라인 모드로 전환
- 로깅: 오류 발생 시 로그를 수집하여 디버깅에 활용
클라이언트 오류 (400번대)
클라이언트 오류(1001, 1002, 1003, 1004, 1005, 1006, 1012)는 다음과 같이 처리하는 것이 좋습니다:
- 사용자 피드백 제공: 오류 원인을 사용자 친화적인 메시지로 표시
- 입력 데이터 검증: 사용자 입력 검증 로직 강화
- 재시도 자제: 동일한 요청 재시도는 같은 결과를 반환할 가능성이 높음
- 상황별 UI 대응: 오류 유형에 따라 적절한 UI 처리 (예: 404는 '찾을 수 없음' 페이지 표시)
재시도 가능한 오류
다음 오류가 발생한 경우 적절한 지연 후 재시도할 수 있습니다:
- 1007 (INTERNAL_SERVER_ERROR): 서버 내부 오류
- 1008 (SERVICE_UNAVAILABLE): 서비스 일시 불가
- 1010 (NETWORK_ERROR): 네트워크 오류
- 1011 (TIMEOUT_ERROR): 타임아웃 오류
- 1013 (TOO_MANY_REQUESTS): 요청 횟수 초과
- 1014 (RATE_LIMIT_EXCEEDED): 초당 요청 제한 초과
- 1015 (QUOTA_EXCEEDED): 할당량 초과
- 1016 (RETRY_AFTER): 재시도 대기 필요
노트
속도 제한(Rate Limiting) 관련 오류(1013-1016)는 재시도 시 반드시 서버가 제공하는 Retry-After 헤더나 응답의 metadata.retryAfterSeconds 값을 준수하여 충분한 대기 시간 후에 재시도해야 합니다. 이를 무시하고 즉시 재시도할 경우 IP 차단(1017)과 같은 더 심각한 제한이 발생할 수 있습니다.
재시도 불가능한 오류
다음 오류는 재시도해도 동일한 결과가 예상되므로, 사용자 개입이 필요합니다:
- 1001 (VALIDATION_ERROR): 유효성 검증 오류
- 1002 (NOT_FOUND): 리소스 없음
- 1003 (UNAUTHORIZED): 인증 필요
- 1004 (FORBIDDEN): 권한 없음
- 1005 (BAD_REQUEST): 잘못된 요청
- 1006 (CONFLICT): 충돌 발생
- 1012 (UNPROCESSABLE_ENTITY): 처리 불가능한 엔티티
- 1017 (IP_BLOCKED): IP 차단 (관리자 문의 필요)
변경 이력
| 버전 | 날짜 | 작성자 | 변경 내용 |
|---|---|---|---|
| 0.1.0 | 2025-05-01 | bok@weltcorp.com | 최초 작성 |
| 0.47.0 | 2025-09-09 | jeff@weltcorp.com | ValidationErrorDetail 인터페이스 추가, errors 배열 형식 상세화, 실제 WCS URI validation 케이스 반영 |