에러 응답 표준화 및 사용자 노출 메시지 안전화

[IENFI]

🔨 Describe

현재 에러 처리 방식은 백엔드와 프론트에서 기준이 일관되지 않아, 사용자에게 내부 에러 메시지나 라이브러리/DB 원본 메시지가 그대로 노출될 수 있다.
이번 작업의 목표는 다음과 같다.

• 사용자에게는 항상 안전한 메시지만 노출한다.
• 내부에서는 원본 에러를 로그/Sentry로 추적 가능하게 유지한다.
• 백엔드와 프론트가 동일한 에러 코드 체계를 사용하도록 맞춘다.
• 프론트는 message보다 code를 우선 신뢰하도록 처리 기준을 정리한다.

핵심 원칙은 다음과 같다.

• 아는 에러만 사용자용 메시지를 보여준다.
• 모르는 에러는 항상 공통 메시지로 치환한다.
• 사용자 응답에는 원본 message, stack, query, constraint 등 기술적 상세를 포함하지 않는다.
• 백엔드는 모든 예외를 code + safeMessage (+ requestId) 형태로 정규화한다.

표준 응답 예시:

{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "일시적인 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.",
    "requestId": "req_123456"
  }
}

권장 표준 에러 코드는 다음을 기본으로 사용한다.

• BAD_REQUEST
• VALIDATION_ERROR
• UNAUTHORIZED
• FORBIDDEN
• TOKEN_EXPIRED
• INVALID_TOKEN
• NOT_FOUND
• CONFLICT
• INTERNAL_SERVER_ERROR
• NETWORK_ERROR

✅ Tasks

• 백엔드 전역 예외 필터에서 모든 예외를 code + safeMessage + requestId 형태로 정규화한다.
• 비즈니스적으로 의도한 예외만 사용자 메시지를 그대로 노출하고, 나머지 unknown/DB/library 에러는 공통 메시지로 치환한다.
• 인증/인가 예외를 UNAUTHORIZED, FORBIDDEN, TOKEN_EXPIRED, INVALID_TOKEN 등 표준 코드로 매핑한다.
• 원본 에러 정보는 응답에서 제거하고, 로그/Sentry에는 원본 에러와 requestId를 함께 남긴다.
• 프론트에 error.code -> 사용자 문구 매핑 테이블을 추가한다.
• 프론트 getErrorMessage()를 message 우선 방식에서 code 우선 방식으로 변경한다.
• 전역 토스트/에러 처리부에서 raw error.message를 직접 사용하지 못하도록 공통 매핑 함수를 거치게 한다.
• 폼 검증 오류와 시스템 오류를 구분해서 표시하도록 UI 처리 기준을 정리한다.
• 알 수 없는 code는 항상 공통 문구로 fallback 되도록 처리한다.
• 주요 API 에러 응답과 프론트 표시 흐름에 대한 테스트를 보강한다.

🙋🏻 More

운영 기준:

• 4xx는 사용자 행동으로 해결 가능한 경우가 많으므로 안내 메시지를 비교적 구체적으로 제공한다.
• 5xx는 내부 문제일 가능성이 높으므로 공통 메시지로 통일한다.
• 사용자에게는 해결 방법만 보여주고, 기술적 상세는 노출하지 않는다.

예시 사용자 메시지:

• UNAUTHORIZED -> 로그인이 필요합니다.
• FORBIDDEN -> 이 작업을 수행할 권한이 없습니다.
• TOKEN_EXPIRED -> 로그인 시간이 만료되었습니다. 다시 로그인해 주세요.
• VALIDATION_ERROR -> 입력값을 확인해 주세요.
• CONFLICT -> 이미 처리된 요청이거나 중복된 데이터입니다.
• INTERNAL_SERVER_ERROR -> 일시적인 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.
• NETWORK_ERROR -> 네트워크 오류가 발생했습니다. 연결 상태를 확인해 주세요.

완료 기준:

• 사용자는 raw 에러 메시지를 직접 보지 않는다.
• 프론트는 error.code 기준으로 메시지를 결정한다.
• 백엔드 응답 형식이 예외 유형과 무관하게 일관된다.
• 운영자는 requestId와 로그/Sentry를 통해 원본 에러를 추적할 수 있다.