무료 티어 AI API를 운영 환경에 도입하며 겪은 실패와 복구 기록 (2026년 2월)

핵심 결론

kimura512.dev의 챗 기능은 무료 티어 AI API를 운영 환경에서 사용하고 있습니다. 무료 티어는 본질적으로 개발용이라는 전제를 깔고, 운영 환경에서는 유연한 폴백과 사용량 가시화가 필수입니다. 2026년 2월 심야 트래픽 집중과 예고 없는 모델 ID 폐기로 장애를 겪은 뒤 정비한 실전 대응책을 정리합니다.

1. HTTP 429 레이트 리밋 대응

소규모 개인 사이트라도 순간적인 요청 집중에 따라 HTTP 429 상태 코드가 반환됩니다. 본 서비스는 3개 프로바이더를 우선순위에 따라 순차 호출하도록 설계했습니다. 제1후보가 실패하면 즉시 제2후보로 넘기며, 화면에는 백엔드 공급자 정보를 노출하지 않고 일관된 안내만 제공합니다.

2. 모델 ID 수명 주기 관리

문서에 명시된 모델명이 사전 공지 없이 지원 중단되는 사례가 있습니다. 코드에 모델명을 하드코딩하면 변경 시마다 빌드와 재배포가 불가피합니다. 환경 변수와 Workers 시크릿을 통해 설정을 분리하여, 코드 수정 없이 즉각 핫스왑할 수 있는 구조를 구축했습니다.

3. 로그에 반드시 남겨야 할 지표

장애 발생 후 사후 분석을 위해 일시(JST), 프로바이더 식별자, HTTP 응답 코드, 토큰 추정치를 구조화 로그로 보관합니다. 막연한 체감 대신 정량적 로그를 기반으로 프로바이더 호출 순위를 재조정합니다.

4. 2026년 2월 18일 장애 복구 사례

Groq 서비스의 일시적 503 에러로 폴백 노드까지 부하가 전파된 적이 있습니다. 기능 플래그를 활용해 AI 어시스턴트 기능만 신속히 비활성화하고 본체 웹사이트는 중단 없이 유지했습니다. 이튿날 라우팅 순서와 타임아웃 설정을 보강했습니다.

5. 가벼운 외형 감시 체계

엔터프라이즈급 모니터링 툴 대신 단일 헬스체크 엔드포인트를 유지하고 주간 단위로 5xx 에러 건수를 점검합니다. 1인 개발에서는 유지 가능한 미니멀한 운영선이 핵심입니다.

6. 서킷 브레이커와 사용자 보호

모든 외부 API가 응답하지 않을 경우, 복잡한 스택 트레이스 대신 "잠시 후 다시 시도해 주세요"라는 정돈된 문구로 우아하게 폴백 처리합니다.

7. 정기적인 이용 약관 감사

무료 티어의 상업적 이용 가능 여부는 수시로 개정됩니다. 분기별로 약관을 재검토하고 검토 일자를 시스템 문서에 명시해 법적 리스크를 통제합니다.

운영 메모

Q. 무료 티어만으로 서비스 지속이 가능한가?
초기 프로토타입 검증은 가능하나, 장기 운영을 위해서는 멀티 벤더 의존성 격리가 선행되어야 합니다.

Q. 로그 추적 방식은?
요청마다 고유한 Request ID를 발급하여 엣지와 백엔드 로그를 상호 대조합니다.

Q. 에러 화면 표출 원칙은?
내부 기술 스택과 에러 코드는 숨기고 단순한 재시도 안내만 노출합니다.