TL;DR — 항목별 실패 메시지를 자유 문자열로 저장했는데, 외부 API 예외 메시지에 업스트림 응답 본문이 통째로 들어 있었다. 이 값이 인증 없는 조회 응답에 그대로 실렸다. 규칙을 문서로 적는 대신, 위반이 컴파일과 테스트에서 실패하도록 타입과 검사로 강제했다.

배경

• 프로젝트/기능: DeployHub — 패키징 Job의 진행률과 항목별 실패 사유를 돌려주는 조회 API
• 환경: Java 17, Spring Boot 3.5
• 특징: 이 조회는 로그인이 없다 — 담당자가 링크로 바로 보는 용도다

문제 (증상)

• 실패한 항목의 error_message에 서버 경로·호스트·업스트림 응답 본문이 그대로 들어간다
• 그 값이 무인증 조회 응답에 실려 링크를 아는 누구나 볼 수 있다

원인 분석

• 실패 사유를 String으로 받는 API가 있었고, 거기에 예외 메시지를 그대로 넣고 있었다
• 외부 HTTP 클라이언트의 예외 메시지는 400 Bad Request: "<응답 본문>" 형태라 업스트림 본문이 통째로 들어 있다(URL은 안 들어가지만 본문은 들어간다는 걸 실측으로 확인했다)
• 근본 원인은 "어떤 문구가 밖으로 나가도 되는가"가 관례로만 관리되고 있었다는 점이다. 문서에 적어두면 다음 사람은 읽지 않는다

해결

오류를 enum으로만 정의하고, 각 코드에 노출 등급(응답 노출 / 로그 전용)을 부여했다. 그리고 세 겹으로 강제한다.

1. 실패 기록 API가 문자열을 아예 받지 않는다 — enum만 받으므로 임의 문구를 넣을 수가 없다
2. 로그 전용 코드로는 예외를 만들 수 없다 — 응답으로 나갈 경로에서 원천 차단
3. 테스트가 문구를 검사한다 — 응답 노출 코드의 메시지에 경로·호스트 패턴이 없는지, HTTP 상태가 붙은 코드가 제대로 등급이 붙었는지 확인

• 상세 맥락은 로그 전용 경로로만 넘기도록 분리했다 — 디버깅에 필요한 정보를 버리지 않으면서도 밖으로는 안 나간다
• 예전에는 코드가 메서드 본문에 문자열로 흔어져 있었는데, 이를 단일 enum으로 모아 오류 코드의 출처를 하나로 만들었다

결과