은행 입금 연동 오류 응답 파싱과 필수값 검증 개선

사건 요약

• 은행 파트너 입금 호출에서 간헐적 실패가 발생, 사용자 화면에는 "처리 실패"만 노출됨
• Step2 진입 시 일부 필수값이 누락된 채 호출되어 NPE 로 흐름이 끊김
• 운영팀이 원인 파악을 못해 같은 케이스를 반복 문의받았음

두 갈래로 손봄

입금 유틸의 응답 파싱과 Step2 입력 검증, 두 군데를 같은 변경에 묶었음.

응답 파싱은 그동안 HTTP 200 만 보고 본문을 그대로 신뢰했는데, 은행 쪽이 200 으로 떨어뜨리면서 본문 안에 에러 코드를 박아 주는 케이스가 있었음. status 만 본 게 패착. 본문에서 에러 코드를 먼저 들여다본 뒤 분기하도록 바꿨음.

ErrorCode err = peekErrorCode(body);
if (err != null) {
    log.warn("deposit fail code={} raw={}", err.code(), body);
    throw new PartnerDepositException(err);
}
return parseDeposit(body);

Step2 검증은 호출자가 알아서 값을 채워 넣을 거라 가정하고 그냥 통과시켰는데, 한 화면에서 누락 케이스가 있었음. 진입부에서 빠진 키만 모아 한 번에 예외로 던지도록 변경. 한 번에 묶어 던져야 운영자가 어떤 필드가 비었는지 한눈에 봄.

회고

• 결제대행사·은행 파트너는 200 OK 본문에 에러를 박는 경우가 흔함. status code 만 믿으면 안 됨
• "호출자가 채워 넣겠지" 라는 가정은 거의 항상 깨짐. 진입부 한 줄 검증이 결국 이김
• 사용자에게 보여줄 메시지와 운영자용 raw 로그는 분리해야 추후 분석이 가능함
• 두 수정을 같은 변경에 묶은 게 정답이었음. 한쪽만 고치면 다른 쪽 케이스에서 또 같은 모습으로 실패함
• 다음에 비슷한 외부 연동 붙일 때는 처음부터 응답 본문 파싱 + 진입부 검증을 템플릿으로 깔고 시작하기로 함

다음