운세 생성 타임아웃 연장으로 간헐적 실패 해결

어느 날 운세 생성 스크립트가 자주 실패한다는 보고를 받았다. 같은 프롬프트로 실행해도 어떨 때는 성공하고 어떨 때는 도중에 끝나버리는 식이었다. 원인을 추적하다 보니 Claude API 호출 타임아웃이 90초로 설정되어 있었는데, 복잡한 생성 작업이 이를 초과하는 경우가 빈번했던 것. 이를 300초로 늘리는 간단한 수정인데, 생각보다 많은 걸 배우게 한 작업이었다.

타임아웃, 너무 촉박하지는 않았나

스크립트가 실패하는 패턴을 들여다보니 명확했다. 생성 로직이 복잡할수록, 프롬프트가 길수록 Claude API가 응답을 완성하는 데 더 오래 걸렸다. 특히 여러 단계의 추론이 필요한 작업에서는 90초 제한이 너무 타이트했던 것 같다.

타임아웃 설정은 한 번 정해지면 쉽게 주목받지 않는데, 이게 얼마나 중요한지 생각해보면:

• 90초 설정의 의도: 아마도 초기 개발 단계에서 "대부분의 요청은 이 정도면 충분하겠지"라는 가정 하에 설정된 것
• 현실의 변화: 시간이 지나며 생성 로직이 복잡해지고, 사용자가 요청하는 콘텐츠 길이도 증가
• 침묵하는 실패: 타임아웃으로 실패한 요청은 "왜 안 되지?" 같은 모호한 에러 메시지만 남김

타임아웃 연장의 트레이드오프

300초로 올리기 전에 몇 가지 고민했던 부분들:

결국 이것도 시스템 설계의 근본적인 트레이드오프였다. 사용자 경험 vs 시스템 안정성. 빠른 응답 vs 높은 완성도. 다만 이 경우엔 "자주 실패하는 쪽"이 더 나쁜 UX라고 판단했다.

실제 적용 후 배운 것

// scripts/generate-fortune.js
// Before: timeout 90초
const response = await callClaudeAPI(prompt, { timeout: 90000 });

// After: timeout 300초 (5분)
const response = await callClaudeAPI(prompt, { timeout: 300000 });

단순 수정이지만, 이후로 생각하게 된 부분들:

• 모니터링의 중요성: 타임아웃이 얼마나 자주 발생하는지, 어떤 유형의 요청에서 발생하는지 로깅하지 않았다면 이 문제를 놓쳤을 수 있음
• 기본값의 위력: 한 번 설정한 config는 "이미 검증된" 것으로 간주되는 경향이 있다. 정기적인 재검토 필요
• 비동기 작업의 고려: 만약 사용자가 실시간으로 응답을 기다리는 상황이라면 300초도 길었을 텐데, 배치/스케줄 작업이라는 점이 이 결정을 가능하게 함

다음 스텝과 예방

이런 류의 문제를 다시 겪지 않으려면:

• 타임아웃 설정마다 주석 추가: "왜 이 값으로 설정했는가", "어떤 조건에서 재검토할 것인가"
• 타임아웃 메트릭 수집: 실제로 타임아웃이 얼마나 자주 발생하고, 가장 느린 요청이 얼마나 오래 걸리는지 추적
• 점진적 증가 테스트: 한 번에 300초로 올리기보다 120초 → 180초 → 300초처럼 단계적으로 올려보기

결국 이 작업은 "설정값 한두 개 변경"이 아니라, 시스템이 성숙하면서 초기 가정들이 얼마나 빨리 구식이 되는지를 상기시켜주었다.

🛒 이 글과 어울리는 추천 상품

• 사무의자 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.