프로덕션 AI API 장애
새벽 2시에 AI 기능이 고장 났을 때, 에러 메시지만으로는 상황을 완전히 파악하기 어렵습니다. 저는 1년 동안 OpenAI와 Anthropic 연동 서비스를 운영하며, 디버깅을 위해 에러를 그 의미에 따라 분류하는 법을 배웠습니다.
속도 제한(Rate Limits) 처리
OpenAI의 429 에러는 원인이 다양합니다. 어떻게 대응할지 결정하려면 에러 코드를 반드시 확인해야 합니다.
- 분당 요청 수(RPM) 제한은 몇 초 내에 복구됩니다.
- 분당 토큰 수(TPM) 제한은 60초 내에 복구됩니다.
- 월간 할당량 소진은 크레딧을 추가하거나 결제 주기가 갱신될 때까지 해결되지 않습니다.
할당량 문제에 지수 백오프(exponential backoff)를 사용하지 마세요. 시간 낭비일 뿐입니다.
Anthropic의 529 에러는 제공업체의 과부하를 의미합니다. 이를 503 에러처럼 취급하세요. 문제는 그들 쪽에 있습니다. 잠시 요청을 멈추고 팀에 알리세요.
400 에러 처리
이러한 실패는 대개 사용자 측의 잘못입니다. 다음 세 가지 패턴을 주의 깊게 살펴보세요.
- 모델 버전 불일치. 한 곳에서는 이름을 업데이트했지만 재시도 핸들러(retry handler)에서는 업데이트하지 않은 경우입니다.
- 컨텍스트 윈도우(Context window) 초과. 대화 기록이 너무 커진 경우입니다. 이는 주로 잘못된 절단(truncation) 로직 때문에 발생합니다.
- 스키마 검증 실패. JSON 구조에 지원되지 않는 타입이 있거나 재귀적 참조가 포함된 경우입니다.
이를 해결하려면 400 에러 발생 시 전체 요청 페이로드를 로그로 남기세요. 먼저 사용자 데이터를 마스킹(redact)해야 합니다. 응답 본문(response body)을 보면 어떤 필드에서 오류가 발생했는지 정확히 알 수 있습니다.
타임아웃 처리
타임아웃은 제공업체 측에서 아무런 문제가 없다고 판단하기 때문에 추적하기 어렵습니다.
- 연결 타임아웃(Connect timeout). 핸드셰이크(handshake)에 실패한 경우입니다. 제공업체의 일시적 장애(brownout)나 DNS 문제 시 발생합니다. 아웃바운드 네트워크를 확인하세요.
- 읽기 타임아웃(Read timeout). 모델이 시작은 했으나 완료하지 못한 경우입니다. 앱은 부분적인 스트리밍 출력(partial streaming outputs)을 처리할 수 있어야 합니다.
- 게이트웨이 타임아웃(504). 프록시가 먼저 타임아웃된 경우입니다. 요청은 제공업체 측에서 여전히 실행 중일 수 있습니다. 재시도하기 전에 중복 제거(deduplication)를 사용하세요.
디버깅을 위해 연결 타임아웃과 읽기 타임아웃을 분리하세요. 첫 번째 토큰 생성 시간(time-to-first-token)을 로그로 남겨 지연(latency)이 어디서 발생하는지 확인하세요.
제공업체 문제 처리
- 500 에러는 2초 후 한 번의 재시도로 해결되는 경우가 많습니다.
- 503 에러는 서비스 성능이 저하되었음을 의미합니다. 제공업체의 상태 페이지(status page)에 장애가 표시되어 있다면 서킷 브레이커(circuit breaker)를 사용하세요.
- 어떤 모델 버전이 실패했는지 항상 기록하세요. 모델마다 신뢰도 수준이 다릅니다.
로그를 확인하자마자 슬랙(Slack)으로 달려가지 마세요. 먼저 제공업체의 상태 페이지를 확인하세요. 그러면 20분 동안 당황할 일을 줄일 수 있습니다.
Optional learning community: https://t.me/GyaanSetuAi