docs: HTTP 상태 코드별 에러 처리 규칙 추가

- 404/504는 재시도 가능 에러로 처리
- 500은 즉시 중단 및 명확한 사용자 메시지 제공
- 동일 템플릿 메시지 사용 금지 원칙 추가
- HTTP 레벨 에러와 사용자 메시지 분리 원칙 명시
This commit is contained in:
Claude-51124 2025-12-02 02:18:53 +09:00
parent b959e90dd2
commit 3098ffb2e1

View File

@ -122,12 +122,31 @@ src/
## 9. 에러 처리 일관성 원칙
**핵심 원칙**: 환경별 일관된 에러 로깅
**핵심 원칙**: 환경별 일관된 에러 로깅 및 HTTP 상태 코드별 처리
- `console.error` 대신 환경별 로깅 유틸리티 사용
- 프로덕션 환경에서도 에러 로그 기록
- 로깅 유틸리티는 개발/프로덕션 환경에 따라 적절히 처리
### HTTP 상태 코드별 처리 규칙
**에러 메시지 디자인 원칙**: HTTP 레벨 에러와 사용자 메시지를 분리
- **404 Not Found**: 리소스가 아직 생성되지 않음 → 재시도/폴링 계속 (예: 평가 진행 중)
- **504 Gateway Timeout**: 게이트웨이 타임아웃 → 사용자에게 "분석 시간이 초과되었습니다" 또는 재시도 안내
- **502 Bad Gateway**: 백엔드 연결 실패 → 사용자에게 "서버 연결 오류" 안내, 재시도 제안
- **500 Internal Server Error**: 서버 오류 → 즉시 중단, 사용자에게 "서버 오류가 발생했습니다. 잠시 후 다시 시도해주세요" 안내
**금지 사항**:
- ❌ 모든 에러에 동일한 템플릿 메시지 사용 (예: "(템플릿) 평가 처리 중 오류가 발생했습니다")
- ❌ HTTP 상태 코드를 사용자에게 직접 노출
- ❌ 에러 원인 파악 없이 일반적인 메시지만 표시
**권장 사항**:
- 에러 유형별로 명확한 사용자 메시지 제공
- 원인 파악은 HTTP 상태 코드와 백엔드 로그로 교차 검증
- 폴링/재시도 가능한 에러(404, 504)와 치명적 에러(500)를 구분하여 처리
## 10. 데이터 검증 원칙
**핵심 원칙**: 백엔드 응답 구조 검증 및 폴백 처리