diff --git a/book/300_architecture/313_React_구조_원칙.md b/book/300_architecture/313_React_구조_원칙.md index 23460fd..4d1b7d3 100644 --- a/book/300_architecture/313_React_구조_원칙.md +++ b/book/300_architecture/313_React_구조_원칙.md @@ -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. 데이터 검증 원칙 **핵심 원칙**: 백엔드 응답 구조 검증 및 폴백 처리