주소정제 서비스 내재화 - 2화 ( 그럴싸한 계획 )

컬리 OMS 팀이 외부 주소정제 업체 호출 비용을 줄이려 행안부 오픈 API와 자체 축적 데이터를 조합해 주소정제 1.0을 설계·배포한 과정과, 배포 직후 겪은 장애를 다룬다. 3개월 만에 외부 호출을 절반 이하로 줄여 월 150~200만원을 아꼈지만, 행안부 API 타임아웃으로 약 1,000건 요청이 실패해 대응 방식을 바꿨다.

핵심 포인트

행안부 도로명 주소조회 API로 건물관리번호(bdMgtSn)를 얻고, 좌표조회 API로 GRS80 UTM-K 위경도를 얻는 두 API를 조합했다.
좌표조회 API는 5초당 10건 제한이라 제약이 커, 5년치 '외부 주소정제 축적 데이터'를 캐시처럼 활용해 좌표를 커버했다.
같은 건물관리번호면 같은 기본주소라는 성질을 이용해, 이미 정제된 다른 고객 데이터로 신규 요청을 채우는 flow를 설계했다.
AS-IS 테스트 점검 → latency 체크 → QA → 운영 카나리 일주일 모니터링의 보수적 배포 계획을 따랐다.
배포 후 행안부 주소조회 API가 5~10분간 타임아웃/502를 내며 캐시에 없는 주소 요청이 대량 실패했다.

상세 정리

목표 설정: 계약 종료는 멀게 느껴져, 일단 외부 업체 API 호출 비용만이라도 최소화하는 것을 1차 목표로 잡았다.
API 발견: 도로명·지번을 넣으면 건물관리번호까지 주는 주소조회 API와, 도로명코드·본번·부번으로 위경도를 주는 좌표조회 API를 찾았다.
제약 확인: 담당자 통화로 주소조회는 쿼리 제한 없음, 좌표조회는 5초당 10건 제한, 과도한 요청은 IP 차단 가능이라는 조건을 파악했다.
좌표 확보 아이디어: 좌표 API 제한이 커서, 계약 시 허락받아 캐싱해둔 5년치 정제 주소 데이터로 건물 좌표를 대체 조달하기로 했다.
가설 검증: 운영에서 외부 API로 호출됐던 주소 50~100개를 무작위로 찍어 커버 가능성을 확인하고 충분하다고 판단했다.
정제 1.0 flow: STEP1은 주소조회 API로 건물관리번호를 얻어 축적 DB에서 정제 주소를 찾고, STEP2는 없으면 좌표조회 API를 시도하는 구조다.
배포 계획: 테스트 코드 점검, latency 영향 체크, QA 검증, 운영 카나리 최소 일주일 모니터링, 간단한 에러는 핫픽스·복잡하면 롤백으로 정했다.
효과: 3개월 만에 외부 호출을 절반 이하로 줄여 월 150~200만원을 절감했다.
장애 발생: 배포 일주일 뒤 저녁, 10분간 약 1,000건의 OMS API 응답에서 에러가 났고 결제 중 고객이 재시도를 겪었다.
원인: 주소조회 API가 5~10분간 타임아웃·502를 냈고, 메인 캐시에 없는 주소 요청만 장애 대상이 됐다.
대응: 타임아웃을 더 짧게 줄이고 retry를 제거했으며, 타임아웃 예외 시 무조건 기존 외부업체 호출로 폴백하도록 바꿨다.
재평가: API 안정성을 과신했고, 축적 데이터만으론 신규 고객 주소를 다 못 커버해 외부 업체 계약은 못 끊는다는 한계를 인정하고 방향을 재검토했다.