AI 외부 API 타임아웃 폴백 루프

AI가 외부 API 연동 코드를 만들 때 가장 자주 놓치는 것은 “정상 응답”이 아니라 “응답이 늦거나, 일부만 실패하거나, 과금 한도 때문에 막히는 순간”입니다. 로컬에서는 버튼을 눌렀을 때 한 번 성공하니 기능이 완성된 것처럼 보입니다. 하지만 실제 서비스에서는 외부 모델 호출, 결제 승인, 이메일 발송, 검색 인덱스 조회, 이미지 생성, 지도 조회처럼 다른 시스템에 의존하는 작업이 많습니다. 이때 타임아웃, 재시도, 폴백, 사용자 안내, 로그 기준이 없으면 AI가 만든 기능은 데모에서는 멋지고 운영에서는 불안한 기능이 됩니다.

이 글의 목표는 외부 API를 “부르면 끝”이 아니라 “실패해도 통제 가능한 제품 흐름”으로 설계하는 것입니다. 초보자는 API 호출 코드보다 먼저 실패 화면을 떠올리면 이해가 쉽습니다. 전문가는 호출 경계, 예산, 관측성, 승인 기준, 중단 기준을 숫자로 고정해야 합니다. VIBE 코딩에서는 이 두 관점을 동시에 AI에게 줘야 합니다.

핵심 결론

외부 API 연동은 성공 케이스 한 줄보다 실패 루프 네 가지가 더 중요합니다. 첫째, 언제까지 기다릴지 정하는 타임아웃입니다. 둘째, 어떤 실패만 다시 시도할지 정하는 재시도입니다. 셋째, 재시도 후에도 안 될 때 사용자가 계속 작업할 수 있게 하는 폴백입니다. 넷째, 장애인지 일시 지연인지 판단할 수 있는 로그와 지표입니다.

AI에게 “외부 API 붙여줘”라고 말하면 보통 SDK 예제와 정상 응답 매핑만 만듭니다. 반대로 “2.5초 응답 제한, 네트워크 오류 2회 재시도, 429·402 계열은 재시도 금지, 사용자에게 임시 저장 안내, 요청 식별자 기반 로그, 공개 화면에는 내부 인증값 노출 금지”처럼 경계를 주면 결과물이 운영 가능한 코드에 가까워집니다.

좋은 API 연동의 완료 기준은 “한 번 성공했다”가 아닙니다. 느린 응답, 끊긴 네트워크, 잘못된 입력, 권한 부족, 사용량 제한, 외부 장애, 부분 성공, 중복 요청을 각각 어떻게 처리하는지 확인했을 때 완료입니다.

왜 중요한가

외부 API는 내 코드가 통제할 수 없는 시간을 서비스 안으로 가져옵니다. 사용자는 버튼을 눌렀고, 내 서비스는 기다리는 중이고, 외부 시스템은 바쁠 수 있습니다. 이 간극을 설계하지 않으면 화면은 멈춘 것처럼 보이고, 사용자는 같은 버튼을 여러 번 누르며, 서버는 중복 요청을 보내고, 비용은 늘고, 운영자는 원인을 찾지 못합니다.

특히 AI 코딩에서는 위험이 커집니다. AI는 SDK 문서의 가장 짧은 예제를 빠르게 붙입니다. 예제는 학습용이라 타임아웃, 취소, 지수 백오프, 중복 방지, 사용자 메시지, 실패 로그가 빠진 경우가 많습니다. 사람이 리뷰하지 않으면 “작동은 하지만 운영 기준이 없는 코드”가 그대로 배포됩니다.

실제 제작 루프에서는 외부 API 연동을 다음 세 영역으로 나눠야 합니다.

사용자 경험 경계

사용자는 무엇을 기다리고 있는지 알아야 합니다. 1초 이내 작업은 버튼 비활성화와 짧은 로딩으로 충분할 수 있습니다. 3초를 넘는 작업은 진행 상태나 대체 행동이 필요합니다. 10초를 넘는 작업은 백그라운드 작업, 이메일 알림, 나중에 다시 보기 같은 별도 흐름이 필요합니다. AI에게 이 기준을 주지 않으면 모든 호출이 같은 로딩 스피너로 처리됩니다.

시스템 경계

서버는 외부 API가 느려도 무한히 대기하면 안 됩니다. 요청 단위 타임아웃, 전체 작업 타임아웃, 동시 요청 제한, 재시도 횟수, 멱등성 키, 큐 분리 기준을 정해야 합니다. 예를 들어 결제 승인, 콘텐츠 생성, 검색 요약은 모두 외부 호출이지만 실패 비용과 재시도 가능성이 다릅니다. 결제성 요청은 중복 재시도가 위험하고, 읽기성 검색 요청은 짧은 재시도가 비교적 안전합니다.

운영 경계

운영자는 어떤 실패가 몇 번 발생했는지 알아야 합니다. 단순히 “failed”만 남기면 원인을 알 수 없습니다. 타임아웃, 외부 제한, 인증 실패, 입력 오류, 외부 5xx, 응답 파싱 실패, 사용자 취소를 구분해야 합니다. 단, 로그에는 민감한 인증 문자열이나 원문 개인정보를 남기면 안 됩니다. 저장할 것은 요청 흐름을 이해하는 데 필요한 식별자, 상태, 시간, 재시도 횟수, 안전하게 축약한 오류 종류입니다.

실제 작업 순서

아래 순서대로 진행하면 AI가 만든 API 연동을 운영 가능한 루프로 바꿀 수 있습니다.

1단계: 호출 목적을 분류한다

먼저 외부 API 호출이 읽기 작업인지, 쓰기 작업인지, 비용이 발생하는 작업인지, 사용자가 즉시 결과를 기다려야 하는 작업인지 분류합니다. 같은 API라도 목적이 다르면 루프가 달라집니다.

AI에게 이 표의 분류를 먼저 주고 구현을 요청하세요. “이 호출은 비용 발생 + 긴 작업이다”라고만 말해도 AI의 설계 방향이 달라집니다.

2단계: 숫자로 타임아웃을 정한다

“적당히 기다린다”는 운영 기준이 아닙니다. 프론트엔드 버튼 응답, 서버 API 라우트, 외부 호출, 전체 작업에 각각 숫자를 둡니다.

예시 기준은 다음과 같습니다.

• 버튼 클릭 후 150ms 안에 로딩 상태를 표시한다.
• 일반 조회는 2.5초 안에 응답하지 않으면 폴백 메시지를 보여준다.
• 서버의 외부 호출은 3초에서 중단한다.
• 비용이 큰 생성 작업은 즉시 응답 대신 작업 ID를 반환하고 백그라운드에서 처리한다.
• 전체 사용자 흐름은 8초를 넘기면 “나중에 확인” 경로를 제공한다.

이 숫자는 정답이 아니라 출발점입니다. 중요한 것은 숫자가 있다는 점입니다. 숫자가 있어야 테스트도 만들 수 있고, 장애 기준도 만들 수 있습니다.

3단계: 재시도 가능한 실패만 고른다

모든 실패를 재시도하면 비용과 장애를 키웁니다. 재시도할 수 있는 것은 일시적 네트워크 실패, 외부 5xx, 연결 초기화, 짧은 타임아웃처럼 다시 요청하면 성공할 가능성이 있는 실패입니다. 반대로 입력 오류, 권한 부족, 사용량 제한, 결제 필요, 명확한 검증 실패는 재시도하지 않는 편이 안전합니다.

재시도는 보통 1~2회로 시작하고, 짧은 지연을 둡니다. 동시에 모든 사용자가 재시도하면 외부 시스템에 더 큰 부하를 줄 수 있으므로 약간의 무작위 지연을 섞는 것이 좋습니다. AI에게는 “무조건 retry”가 아니라 “재시도 허용 오류 목록과 금지 오류 목록을 분리하라”고 지시해야 합니다.

4단계: 폴백을 제품 기능으로 설계한다

폴백은 “죄송합니다” 문구가 아닙니다. 사용자가 계속 전진할 수 있게 하는 대체 경로입니다. 검색 추천이 실패하면 최근 인기 항목을 보여줄 수 있습니다. AI 요약이 실패하면 원문 저장 후 나중에 다시 생성할 수 있습니다. 결제 상태 확인이 늦으면 중복 결제를 막고 확인 중 상태를 보여줄 수 있습니다. 지도 API가 실패하면 주소 텍스트와 고객센터 안내를 유지할 수 있습니다.

폴백을 설계할 때는 사용자에게 거짓 확신을 주면 안 됩니다. “완료되었습니다”가 아니라 “요청을 접수했고 확인 중입니다”처럼 실제 상태를 말해야 합니다.

5단계: 멱등성과 중복 제출을 막는다

외부 API 연동에서 가장 무서운 실패는 같은 작업이 두 번 실행되는 것입니다. 사용자가 버튼을 여러 번 누르거나, 브라우저가 재전송하거나, 서버가 재시도하면서 중복 생성·중복 결제·중복 발송이 생길 수 있습니다.

쓰기성 요청에는 멱등성 키를 둡니다. 사용자의 의도 하나를 대표하는 키를 만들고, 같은 키가 다시 들어오면 기존 결과를 반환하거나 “처리 중” 상태를 반환합니다. 프론트엔드에서는 버튼을 비활성화하지만, 버튼 비활성화만으로는 충분하지 않습니다. 서버도 같은 요청을 알아볼 수 있어야 합니다.

6단계: 로그와 알림을 운영 언어로 정리한다

운영 로그는 개발자를 혼내기 위한 기록이 아니라 다음 판단을 빠르게 하기 위한 증거입니다. 적어도 다음 항목은 남겨야 합니다.

• 기능 이름과 외부 호출 종류
• 내부 요청 식별자
• 성공, 타임아웃, 제한, 입력 오류, 외부 장애 같은 안전한 상태 코드
• 걸린 시간
• 재시도 횟수
• 폴백 사용 여부
• 사용자에게 보여준 공개 상태

절대 남기면 안 되는 것은 원문 인증 문자열, 결제 민감값, 개인 식별 원문, 외부 서비스의 전체 응답 원문입니다. 필요한 경우에는 일부를 마스킹하거나 길이를 제한한 요약만 남깁니다.

상황별 예시

예시 A: AI 요약 버튼이 느릴 때

사용자가 긴 문서를 붙여 넣고 “요약 생성”을 누릅니다. AI 모델 API가 2초 안에 응답하면 결과를 바로 보여줍니다. 2초를 넘으면 “요약을 생성 중입니다. 이 화면을 닫아도 기록에서 확인할 수 있습니다”라고 안내하고 작업 ID를 저장합니다. 10초를 넘으면 백그라운드 상태로 전환합니다. 모델 호출이 실패하면 원문은 저장하고 “요약 재생성” 버튼을 나중에 제공합니다.

이 예시에서 중요한 것은 요약 실패가 문서 저장 실패로 이어지지 않는다는 점입니다. 핵심 사용자 가치가 “문서 보관”이라면 AI 요약은 부가 기능입니다. AI 부가 기능 실패 때문에 전체 작업을 실패시키지 않는 것이 좋은 폴백입니다.

예시 B: 결제 확인이 지연될 때

결제 승인 요청은 읽기성 조회처럼 마음대로 재시도하면 안 됩니다. 사용자가 결제 버튼을 누르면 서버는 주문 ID와 멱등성 키를 만들고 한 번의 결제 의도를 기록합니다. 외부 결제 응답이 늦으면 “확인 중” 상태를 저장하고 사용자가 버튼을 다시 눌러도 같은 주문 상태를 보여줍니다. 결제 완료 여부는 웹훅이나 상태 조회로 보강합니다.

여기서 AI에게 필요한 지시는 “결제 API 호출 실패 시 동일 요청을 새 결제로 재생성하지 말라”입니다. 초보자는 버튼 비활성화만 떠올리지만, 실제 방어선은 서버의 주문 상태 모델입니다.

예시 C: 추천 목록 API가 실패할 때

홈 화면 추천 목록은 실패해도 서비스 전체가 죽으면 안 됩니다. 외부 추천 API가 늦으면 캐시된 추천, 최근 인기 항목, 편집자가 고정한 기본 목록을 보여줍니다. 사용자에게는 “추천을 불러오지 못했습니다”보다 “최근 많이 본 항목을 먼저 보여드립니다”가 더 낫습니다. 운영 로그에는 추천 폴백이 몇 퍼센트 발생했는지 남깁니다.

이 예시는 폴백이 제품 경험을 망치는 것이 아니라 안정성을 높이는 기능이 될 수 있음을 보여줍니다.

실패 모드와 주의점

첫 번째 실패 모드는 무한 대기입니다. 외부 응답을 기다리느라 서버 연결이 오래 유지되고, 사용자는 같은 요청을 반복합니다. 해결책은 명시적 타임아웃과 사용자 안내입니다.

두 번째 실패 모드는 재시도 폭주입니다. 외부 장애가 이미 발생했는데 우리 서비스가 동시에 재시도하면 장애를 키웁니다. 해결책은 재시도 횟수 제한, 지수 백오프, 회로 차단 기준입니다.

세 번째 실패 모드는 중복 실행입니다. 쓰기성 작업에서 같은 의도가 여러 번 처리됩니다. 해결책은 멱등성 키, 서버 상태 저장, 중복 요청 응답 정책입니다.

네 번째 실패 모드는 조용한 품질 저하입니다. 폴백이 너무 자주 쓰이는데 아무도 모릅니다. 해결책은 폴백 사용률을 지표로 남기고 기준을 넘으면 작업을 중단하거나 승인 절차를 요구하는 것입니다.

다섯 번째 실패 모드는 내부 정보 노출입니다. 에러 원문을 사용자에게 그대로 보여주거나 로그에 민감값을 남기는 경우입니다. 해결책은 공개 오류 메시지와 내부 로그 메시지를 분리하고, 내부 로그도 필요한 최소 정보만 남기는 것입니다.

검증 체크리스트

• 정상 응답뿐 아니라 타임아웃 테스트가 있는가?
• 외부 5xx와 네트워크 오류는 제한적으로 재시도되는가?
• 입력 오류, 권한 부족, 사용량 제한은 재시도하지 않는가?
• 쓰기성 요청에는 멱등성 키나 중복 방지 상태가 있는가?
• 사용자가 버튼을 두 번 눌러도 같은 작업이 중복 실행되지 않는가?
• 폴백 화면이 실제 다음 행동을 제공하는가?
• 폴백 사용률, 응답 시간, 재시도 횟수가 로그나 지표로 남는가?
• 공개 오류 메시지에 내부 경로, 인증 문자열, 원문 응답이 섞이지 않는가?
• 외부 장애가 길어질 때 기능을 임시 중단할 기준이 있는가?
• 배포 후 실제 브라우저에서 로딩, 실패, 재시도 UI를 확인했는가?

AI에게 줄 지시 예시

아래처럼 작업 지시를 주면 AI가 단순 SDK 붙이기에서 벗어나 운영 루프를 함께 설계합니다.

외부 API 연동 기능을 구현한다. 정상 응답만 만들지 말고 타임아웃, 재시도, 폴백, 멱등성, 사용자 안내, 로그 기준을 함께 설계한다. 읽기성 요청과 쓰기성 요청을 분리하고, 쓰기성 요청은 중복 실행을 막는다. 2.5초를 넘는 조회는 폴백을 보여주고, 외부 5xx와 네트워크 오류만 최대 2회 재시도한다. 입력 오류와 권한 부족은 재시도하지 않는다. 공개 화면에는 안전한 메시지만 보여주고 내부 인증값이나 외부 응답 원문은 노출하지 않는다. 테스트에는 정상 응답, 타임아웃, 재시도 성공, 재시도 금지 오류, 폴백 표시, 중복 제출 방지가 포함되어야 한다.

더 구체적인 리뷰 지시는 다음과 같습니다.

변경 후에는 테스트 결과와 함께 실패 모드별 증거를 보고한다. 어떤 오류를 재시도했고 어떤 오류를 재시도하지 않았는지 표로 설명한다. 폴백이 사용자에게 어떤 다음 행동을 제공하는지 확인한다. 로그에는 요청 식별자, 상태, 걸린 시간, 재시도 횟수만 남기고 민감한 원문 값은 남기지 않는다. 중단 기준에 도달하면 기능을 공개하지 말고 보류 사유를 보고한다.

이 지시의 장점은 AI가 “기능 구현자”가 아니라 “운영 가능한 흐름을 만드는 동료”로 움직인다는 점입니다.

중단/승인 기준

자동화된 VIBE 코딩 루프에서는 언제 멈출지 미리 정해야 합니다. 다음 조건 중 하나라도 해당하면 배포나 공개를 중단하고 사람이 승인해야 합니다.

• 외부 호출 실패 시 사용자가 데이터를 잃을 수 있다.
• 쓰기성 요청의 중복 실행을 막는 장치가 없다.
• 타임아웃 테스트가 없거나 수동으로도 확인하지 못했다.
• 재시도 금지 오류까지 재시도한다.
• 공개 오류 메시지에 내부 구현 정보가 섞인다.
• 폴백이 실제 다음 행동 없이 실패 문구만 보여준다.
• 비용이 발생하는 호출인데 예산 제한이나 사용자 승인 흐름이 없다.
• 폴백 사용률이 기준보다 높은데도 정상으로 표시한다.

승인 기준은 반대로 명확해야 합니다. 정상 응답, 타임아웃, 재시도 성공, 재시도 금지, 폴백, 중복 제출 방지, 로그 마스킹, 공개 메시지까지 확인되면 작은 범위에서 공개할 수 있습니다. 처음부터 전체 사용자에게 열지 말고 내부 사용자, 일부 트래픽, 특정 기능 플래그처럼 좁은 범위로 시작하는 것이 안전합니다.

다음 단계

오늘 바로 적용하려면 기존 외부 API 연동 하나를 골라 “성공만 테스트한 코드”인지 확인하세요. 그다음 타임아웃 숫자, 재시도 허용 오류, 폴백 화면, 중복 제출 방지, 로그 항목을 한 장짜리 계약으로 적습니다. AI에게는 그 계약을 기준으로 테스트를 먼저 만들고 구현을 고치게 하세요.

외부 API 연동의 품질은 화려한 SDK 사용법이 아니라 실패했을 때 드러납니다. 사용자가 기다릴 수 있는 시간, 다시 시도해도 되는 오류, 대체 행동, 운영자가 볼 증거를 정해두면 AI가 만든 기능도 실제 서비스 속에서 버틸 수 있습니다.