동블

그래프 뷰

ERROR_HANDLING_POLICY

10 min read

외부 API 에러 처리 정책

Status: Current reference

외부 API 오류는 사용자 입력 문제, 운영 설정 문제, 제공기관 장애, 정상 빈 결과를 구분해야 한다. 외부 API의 원문 에러를 사용자에게 그대로 노출하지 않고, ZIP:ON의 dataStatuses, riskSummary, checklist, 관리자 로그로 변환한다.

에러 유형별 처리

에러 유형외부 응답 예시백엔드 예외 후보재시도 여부사용자 메시지로그 필요 여부
정상resultCode=00, 000, INFO-0 등없음없음확인된 정보로 표시필요 시 success log
빈 결과totalCount=0, items 없음예외 아님짧은 TTL 후 재조회 가능조회 결과가 없어 제한 진단으로 안내필요
인증키 오류법정동코드 290, 공공데이터 SERVICE_KEY_IS_NOT_REGISTERED_ERROR 계열설정 예외 또는 UNAVAILABLE재시도보다 관리자 확인외부 API 인증 설정이 필요하다고 안내필수. key 원문 저장 금지
서비스키 만료key expired 계열UNAVAILABLE관리자 조치 후외부 API 인증이 만료되어 자동 조회 불가필수
필수 파라미터 누락missing parameter 계열개발 오류, validation error재시도 전 수정주소/코드 변환이 부족해 조회 불가필수
잘못된 파라미터invalid parameter 계열query validation error재시도 전 수정주소 또는 조회 조건을 다시 확인해야 함필수
서비스 접근 거부access denied 계열UNAVAILABLE설정 확인 후외부 API 접근 권한 확인 필요필수
트래픽 제한quota/rate limit 계열UNAVAILABLE 또는 retryable errorbackoff 후 가능잠시 후 다시 시도하거나 직접 확인 안내필수
서비스 일시 장애제공기관 HTTP 5xx, DB errorretryable external error제한적 재시도 가능외부 기관 응답 실패로 제한 진단필수
타임아웃connect/read timeoutretryable external error짧은 재시도 또는 circuit외부 조회가 지연되어 제한 진단필수
HTTP 4xxbad request, unauthorized 등client/config error보통 재시도 안 함조회 조건 또는 설정 확인 필요필수
응답 파싱 실패XML/JSON 구조 불일치parser error재시도보다 parser 확인외부 응답 해석 실패로 제한 진단필수. raw body 저장은 redaction 후 후보
단건/배열 구조 불일치items.item 객체/배열 차이parser normalization errorparser 수정 후사용자에게는 외부 응답 해석 실패필수
XML/JSON 차이_type=json 구조 다름parser error형식 고정 후외부 응답 형식 확인 필요필수
TLS/프로토콜 불일치문서는 http, 호출은 https 실패 또는 반대config errorbase URL 수정 후자동 조회 설정 확인 필요필수
VWorld Geocoder 필수값 누락PARAM_REQUIREDrequest assembly error재시도 전 수정주소 좌표 변환 요청값 확인 필요필수
VWorld Geocoder key 오류INVALID_KEY, INCORRECT_KEY, UNAVAILABLE_KEYUNAVAILABLE관리자 조치 후VWorld 인증 설정 확인 필요필수
VWorld Geocoder 사용량 초과OVER_REQUEST_LIMITrate limit error당일 재시도 제한좌표 변환 사용량 초과로 제한 진단필수
VWorld 읍면동 경계 빈 결과status=NOT_FOUND, 빈 features예외 아님후속 재조회 가능가능 지역 경계가 없어 지도 표시를 생략필요
VWorld 읍면동 경계 key/권한 오류INVALID_KEY, INCORRECT_KEY, UNAVAILABLE_KEYUNAVAILABLE관리자 조치 후가능 지역 경계 자동 표시가 제한됨필수
VWorld 읍면동 경계 parser 오류GeoJSON 구조 불일치, 좌표 파싱 실패parser errorparser 수정 후해당 가능 지역은 경계 없이 처리. 원형 fallback 금지필수
VWorld 공시가격 빈 결과status=NOT_FOUND, totalCount=0예외 아님조건 보완 또는 최신연도 fallback 확인공시가격 후보가 없다고 안내. 안전 신호로 해석 금지필요
VWorld 공시가격 key/권한 오류resultCode=INCORRECT_KEY 등ERROR 또는 운영 설정 확인관리자 조치 후VWorld 공시가격 인증 또는 API 권한 확인 필요필수
Juso 직접검색 정상errorCode=0없음없음주소 후보 표시필요
Juso 직접검색 빈 결과errorCode=0, totalCount=0예외 아님검색어 보완 후 가능검색된 주소 후보가 없다고 안내필요
Juso 직접검색 key 오류/만료E0001, E0014UNAVAILABLE관리자 조치 후Juso 주소검색 인증 설정 확인 필요필수. key 원문 저장 금지
Juso 직접검색 검색어 오류E0005, E0006, E0008~E0013, E0015INVALID_REQUEST검색어 보완 후 가능주소 검색어를 더 구체적으로 입력하도록 안내필요
Juso 직접검색 시스템 오류-999ERROR제공기관 상태 확인 후Juso 주소검색 응답 실패 안내필수
한국부동산원 R-ONE 정상INFO 000없음없음과거 지표 분석에 사용필요 시 success log
한국부동산원 R-ONE 빈 결과INFO 200예외 아님조건 완화 후 가능해당 기간/지역/항목의 공개 통계가 부족하다고 안내필요
한국부동산원 R-ONE key 제한INFO 300, ERROR 290UNAVAILABLE관리자 조치 후한국부동산원 통계 인증 설정 확인 필요필수. KEY 원문 저장 금지
한국부동산원 R-ONE 필수값 누락ERROR 300request assembly error재시도 전 수정조회 조건 조립 오류로 과거 지표 분석 불가필수
한국부동산원 R-ONE service/path 오류ERROR 310endpoint/config error재시도 전 수정외부 통계 조회 설정 확인 필요필수
한국부동산원 R-ONE paging 오류ERROR 333, ERROR 336request assembly errorpIndex, pSize 수정 후통계 조회 조건 조정 필요필수
한국부동산원 R-ONE traffic 초과ERROR 337rate limit error당일 또는 backoff 후통계 조회량 초과로 제한 분석필수
한국부동산원 R-ONE 제공기관 장애ERROR 500, ERROR 600, ERROR 601retryable external error제한적 재시도 가능제공기관 응답 실패로 제한 분석필수

사용자 메시지 원칙

  • 사용자가 고칠 수 있는 문제: 주소 재검색, 동/호/번지 보완, 계약 목적/금액 입력 보완을 안내한다.
  • 운영자가 고칠 문제: 인증키, base URL, timeout, traffic limit, parser 오류는 관리자 확인 대상으로 분리한다.
  • 제공기관 문제: “외부 공공데이터 조회가 지연되어 제한 진단”처럼 표현한다.
  • 빈 결과: “데이터가 없으므로 안전하다”가 아니라 “최근 거래 또는 공공데이터가 부족해 직접 확인 필요”로 표현한다.

관리자 로그 원칙

external_api_call_logs에는 아래 값만 저장한다.

provider
apiName
endpointPath
serviceKey 없는 requestSummary
resultStatus
httpStatusCode
durationMillis
errorMessage
createdAt

저장하지 않는다.

DATA_GO_KR_SERVICE_KEY
ServiceKey
serviceKey
VWORLD_API_KEY
JUSO_ADDRESS_CONFIRM_KEY
JUSO_ADDRESS_SEARCH_KEY
KAB_R_ONE_API_KEY
원본 등기부등본/계약서/개인정보

공통 status 매핑 후보

외부 상황domain lookup status 후보화면 상태 후보
성공 + 데이터 있음FOUND, SUCCESSsuccess
성공 + 후보 여러 개AMBIGUOUSambiguous
성공 + 데이터 없음NOT_FOUND, EMPTYempty
key 없음/설정 안 됨UNAVAILABLE, NOT_CONFIGUREDunavailable
HTTP/parser/timeout 오류ERRORerror

테스트 기준

외부 API adapter를 추가할 때 최소한 아래를 테스트한다.

  • service key가 비어 있으면 실제 HTTP 호출을 하지 않는가?
  • service key가 한 번만 인코딩되는가?
  • 필수 query parameter가 빠지지 않는가?
  • totalCount=0을 오류가 아닌 빈 결과로 처리하는가?
  • items.item 단건과 배열을 모두 처리하는가?
  • result code 오류를 ERROR 또는 UNAVAILABLE로 구분하는가?
  • parser 실패 로그에 service key나 원본 민감정보가 남지 않는가?

확인 필요

  • 공공데이터 API별 resultCode 값 체계가 서로 다르므로 새 API 추가 시 code map을 이 문서에 추가해야 한다.
  • retry/circuit breaker를 도입할 경우 Resilience4j 또는 Spring Retry 도입 여부를 별도 decision note로 남겨야 한다.

관련 문서