외부 API 연동의 실패 모델: 응답 분류, retry 경계, IntegrationTest
외부 API 연동에서 더 먼저 설계해야 하는 것은 정상 호출 코드가 아니라 실패 응답 분류, retry 경계, 검증 가드라는 점을 운영 사고를 통해 정리한 글이다.
상황
- 같은 시리즈의 외부 API 클라이언트 중 하나가 path segment를 빠뜨린 채 호출했다.
- 정부 API는 이 실패를 평문 오류 본문으로 돌려줬다.
- 애플리케이션은 이를 일반 retry 대상으로 처리했고, 다른 잡까지 영향을 받았다.
외부 API 연동은 보통 정상 호출 코드부터 만든다. 요청을 보내고, 응답을 파싱하고, DTO로 바꾸고, 서비스 로직에 연결한다. 이번 사고를 만든 건 그 반대쪽이었다. path가 빠진 호출, text/plain으로 오는 오류 본문, 일관되지 않은 status code, 그리고 이를 일반 예외로 묶어 계속 재시도하는 코드였다.
이 글의 결론은 외부 API 연동에서는 호출 성공 경로보다 실패 모델을 먼저 설계해야 한다는 것이다. 다만 외부 API는 문서가 부실하거나 HTTP 표준을 따르지 않는 경우가 많아서, 모든 실패를 미리 정의할 수는 없다. 그래서 처음 보는 실패를 빨리 감지하고 테스트와 운영 기준에 반영하는 과정도 함께 필요하다.
원인
같은 kr-go-data-client 모듈에 같은 계열의 클라이언트가 다섯 개 있었다: Pollen, Asos, FeelsLike, KEco, KmaSpecialNews. 대부분 다음 패턴을 따랐다.
- 생성자에서
baseUrl,serviceKey,segmentId를 받는다 - URL은
$baseUrl/$segmentId/{service}/{op}형태로 조립한다
KrGoDataFeelsLikeClient만 segmentId를 받지 않았다. 그래서 $baseUrl?serviceKey=...처럼 path segment가 빠진 채 호출하고 있었다. 코드 주석에는 정상 endpoint가 적혀 있어서, 리뷰에서 다른 클라이언트와 비슷해 보이면 놓치기 쉬웠다.
mock 테스트로는 이 문제가 드러나지 않는다. mock 테스트는 응답을 DTO로 매핑하는 부분을 검증하고, URL 조립은 검증하지 않는다. 실제 API를 호출해야 path 누락을 알 수 있다. 다른 4개 클라이언트에는 실제 API를 호출하는 IntegrationTest가 있었고, FeelsLike에만 없었다.
운영에서 일어난 일은 다음과 같다.
- 호출은 정상처럼 시도된다
- 실제 API는 path 없는 요청에 평문 500이나 형식이 다른 오류 본문을 내려준다
- 애플리케이션은 이를 일반 실패로 처리한다
- retry가 붙어 있어서 실패가 반복된다
호출 코드가 없어서가 아니라, 실패를 어떤 종류로 볼지 정의하지 않은 상태에서 호출 코드를 먼저 만든 것이 문제였다.
외부 API의 실패 응답은 일관되지 않다
문서상 스펙과 실제 실패 응답은 자주 다르다. 정부·공공 OpenAPI는 차이가 더 크다.
기대하는 실패 응답:
- status code가 의미 있게 구분된다
Content-Type이 일관된다- 오류 바디가 JSON 스키마를 따른다
실제 실패 응답:
- 인증 오류인데
text/plain - quota 초과인데
text/xml - SOAP fault인데 200 또는 500
- 같은 계열 API인데 엔드포인트마다 오류 형식이 다름
Ktor에서 ContentNegotiation { jackson() }에 의존해 response.body<Map<String, Any>>()로 처리하면, application/json이 아닌 응답에서 NoTransformationFoundException이 나거나 본문 파싱 실패가 일반 예외로 처리된다.
외부 API를 붙일 때 먼저 확인하는 질문은 다음과 같다.
- 이 API는 정상 응답 외에 어떤 포맷으로 실패할 수 있는가
- 이 실패는 재시도해도 되는가
- 이 실패는 서비스 장애인가, 호출 계약 위반인가, 사용자 입력 문제인가
- 예외 메시지에 남겨야 할 최소 단서는 무엇인가
정부 OpenAPI 계열에서는 Content-Type보다 본문 패턴이 더 정확한 경우가 많았다. OpenAPI_ServiceResponse, <errMsg>, <returnAuthMsg> 같은 패턴이 보이면 파싱 실패가 아니라 API 제공자가 보낸 명시적 fault로 처리한다. 이를 일반 예외로 두면 재시도할 수 있는 일시적 실패와 재시도해도 성공하지 않는 호출이 구분되지 않고, retry가 문제를 키운다.
retry가 장애를 퍼뜨리는 과정
retry는 재시도해도 되는 실패에만 적용할 때 안정성을 높인다. 실패 분류가 틀리면 장애를 키운다.
이번 사례의 흐름:
- path가 잘못된 요청이 나간다
- 외부 API가
text/plain또는 SOAP fault를 돌려준다 - 애플리케이션이 이를 일반 예외로 본다
- 공통 retry 로직이 같은 요청을 반복한다
- dispatcher나 worker pool을 다른 잡과 공유하고 있어서 부하가 번진다
- 겉으로는 외부 API 파싱 실패가 아니라 Quartz misfire, 다른 잡 지연, 운영 로그 폭증으로 보인다
원인과 증상이 분리된다.
- 원래 원인: 외부 API 호출 계약 위반
- 중간 확산: 잘못된 retry 정책
- 최종 증상: 다른 잡 misfire, worker starvation, 로그 폭주
운영에서는 마지막 증상이 먼저 보여서 스케줄러, worker 수, thread pool 설정부터 의심하게 된다. 먼저 고쳐야 하는 건 retry 대상의 정의다.
retry 대상은 최소한 다음처럼 나눈다.
- 네트워크 일시 장애, timeout, 일시적 5xx: retry 가능 후보
- 인증 오류, path 누락, 요청 파라미터 오류, 명시적 OpenAPI fault:
NonRetryable - 파싱 실패: 원문 일부와
Content-Type을 남기고 원인을 분류한 뒤 결정
retry는 예외 처리의 기본값이 아니라, 정의된 실패 분류에 따라서만 적용한다.
가드 1: 같은 시리즈 클라이언트와 패턴 비교
새 클라이언트를 추가할 때는 같은 모듈의 기존 클라이언트와 비교한다.
- 생성자 시그니처가 같은가
- URL 구성 방식이 같은가
- 필요한 path segment, service code, query parameter가 빠지지 않았는가
외부 API 클라이언트는 시리즈별로 패턴이 비슷하다. 하나만 다르면 의도인지 실수인지 확인한다.
가드 2: 클라이언트마다 IntegrationTest
mock 테스트는 파싱 로직과 서비스 조합을 확인하는 데 쓴다. URL 조립, 실제 응답 포맷, Content-Type 변칙, path 누락은 실제 호출로만 확인된다. 그래서 외부 API 클라이언트마다 *IntegrationTest.kt를 둔다.
- 환경변수가 없으면 skip
- 로컬에서는 실제 키를 넣고 수동 실행
- 실제 API를 한 번이라도 호출하면 URL 계약 위반이 드러난다
CI에서 항상 돌리지 못하더라도, 필요할 때 바로 돌릴 수 있는 테스트가 있는 것과 없는 것은 다르다. 이번에도 IntegrationTest가 없는 FeelsLike에서만 path 누락이 늦게 발견됐다.
새 클라이언트 리뷰 체크리스트:
- 같은 시리즈의 기존 클라이언트와 생성자 시그니처가 같은가
- URL 구성에 필요한 path segment가 빠지지 않았는가
*IntegrationTest.kt가 같이 추가됐는가- 비정상 응답이
NonRetryable로 분류되는가
실패 모델을 미리 다 알 수 없을 때
실패 모델을 먼저 정의하려 해도 그럴 수 없는 API가 많다.
- 문서에는 JSON 오류라고 돼 있는데 실제로는
text/plain이 온다 - 4xx/5xx 대신 200에 fault 본문을 싣는다
- 같은 제공자 안에서도 엔드포인트마다 오류 형식이 다르다
이 경우 운영에서 처음 보는 실패를 빨리 감지하고, 다음 코드와 테스트에 반영한다.
1. 실패 단서를 남긴다
외부 API 오류를 일반 예외 한 줄로 남기지 않는다. 최소한 다음을 남긴다.
- status code
Content-Type- 응답 본문 일부
- 클라이언트와 endpoint
이 정보가 있어야 일시적 장애, 호출 계약 위반, 문서와 다른 실패 포맷을 나중에 구분할 수 있다.
2. 본 실패를 테스트로 옮긴다
- IntegrationTest에 실제 재현 케이스 추가
- 또는 parsing/failure classification 테스트에 fixture 추가
같은 코드가 다시 merge되지 않게 하는 것이 목적이다.
3. 팀 기준으로 공유한다
같은 제공자의 다른 API도 비슷하게 실패할 가능성이 높다. 운영에서 본 실패는 팀 기준으로 정리한다.
- 어떤 fault 패턴은
NonRetryable로 본다 - 어떤 제공자는
Content-Type보다 본문 패턴을 먼저 본다 - 새 클라이언트에는
*IntegrationTest.kt를 같이 추가한다
호출 코드 전에 정할 것
보통 먼저 정하는 것:
- 어떤 클라이언트를 쓸까
- DTO는 어떻게 만들까
- 응답 모델은 어떻게 나눌까
- 재시도는 몇 번 할까
그 전에 정해야 하는 것:
- 이 API는 어떤 방식으로 실패하는가
- 어떤 실패는 retry하면 안 되는가
- 어떤 실패는 즉시 경보를 올려야 하는가
- 파싱 실패를 단순 예외로 둘 것인가, 도메인 예외로 승격할 것인가
- 이 실패가 다른 잡과 worker pool에 어떤 영향을 줄 수 있는가
미리 정할 수 있는 것은 먼저 정하고, 정할 수 없는 부분은 모니터링으로 감지해 테스트와 팀 기준에 반영한다.