429, 5xx 및 타임아웃: LLM 게이트웨이 장애 대응의 엔지니어링 실무

먼저 분류하고, 그다음 처리 방법을 결정하세요

'모든 오류를 세 번 재시도한다'는 가장 흔한 잘못된 방식입니다. 오류 코드마다 의미가 완전히 다르므로 처리 전략도 반드시 달라야 합니다. 아래 표는 저희 게이트웨이가 실제로 채택한 전략이며, 직접 구현할 때 참고할 수도 있습니다.

• 연결 실패 / DNS / TLS: 즉시 대체 채널로 전환합니다.
• Timeout(아직 출력 시작 전): 대체 채널로 전환하며, 최대 1~2회입니다.
• HTTP 429: 짧게 냉각한 뒤 채널을 전환하고, 동시에 해당 채널의 가중치를 낮춥니다.
• HTTP 5xx: 실패 윈도에 집계하고, 연속 실패 시 서킷 브레이커를 작동시킵니다.
• 401 / 403: 자격 증명 또는 권한 문제이므로 해당 자격 증명을 비활성화하고 경보를 발생시키며, 재시도하지 않습니다.
• 잔액 부족: 해당 채널을 일시 중지하고 경보를 발생시킵니다.
• 400 파라미터 오류: 정규화한 뒤 그대로 고객에게 반환하며, 재시도하지 않고 과금하지 않습니다.
• SSE가 일부 내용을 출력한 뒤 중단됨: upstream_stream_error를 반환하며, 기본적으로 재시도하지 않습니다.

SSE 중단을 단순히 재시도할 수 없는 이유

스트리밍 응답이 클라이언트에 토큰을 출력하기 시작했다는 것은 업스트림이 이미 (그리고 과금될) 출력을 생성했다는 뜻입니다. 이때 게이트웨이가 몰래 다른 채널로 바꿔 처음부터 다시 하면, 사용자는 내용이 중복되는 것을 보게 되고 당신은 두 출력에 대해 비용을 지불하게 됩니다.

올바른 방법은 이 잘린 스트림을 하나의 부분 성공으로 취급하는 것입니다: 오류 코드를 반환해 클라이언트에게 '업스트림 중단'을 알리고, 이미 나온 내용을 보여주며 재시도 안내를 할지 아니면 전체를 다시 할지는 비즈니스 측이 결정하도록 합니다.

서킷 브레이커: 재시도보다 더 중요한 계층

재시도는 개별 요청에 대한 처리이고, 서킷 브레이커는 일정 기간의 전체 상태에 대한 판단입니다. 특정 채널의 연속 실패가 임계값에 도달하면 바로 '열림'으로 표시하고 일정 기간 동안 트래픽을 보내지 않으며, 그다음 소량의 탐침 트래픽을 보내 시험하고(반열림), 탐침이 여러 번 성공하면 완전히 복구합니다(닫힘).

서킷 브레이커가 없으면 재시도는 이미 죽은 채널을 더욱 압박하고, 고객의 평균 지연도 급격히 높입니다.

재시도의 멱등성과 과금

• 비스트리밍 요청: 재시도 후에는 최종 성공한 그 한 번의 usage로만 과금합니다.
• 스트리밍 요청: 이미 토큰을 출력한 그 시도는 실제로 업스트림 비용을 발생시켰으므로 반드시 기록해야 하며, 재시도했다고 해서 장부를 맞춰 없애면 안 됩니다.
• 각 사용자 요청에 request_id를 할당하고 모든 재시도가 이를 공유하게 하면, 사후에 '왜 이 채널로 갔는지'를 완전히 재현할 수 있습니다.
• 환불/조정은 반드시 원장 거래 내역을 통해 처리해야 하며, 잔액을 직접 수정하면 안 됩니다.

Admesh가 이미 해 둔 것

위 전략은 Admesh 게이트웨이에서 기본 동작입니다: 동일한 public_model의 여러 업스트림 채널 사이에서 자동 전환하며, 모든 라우팅 결정이 데이터베이스에 기록되어 고객이 사용량 기록에서 request_id, 실제 사용된 모델, 채널 상태를 확인할 수 있습니다. 오류 코드는 통일된 형식(error.type / error.code / request_id)으로 반환됩니다.

주목할 점은 라우팅이 동일한 public_model의 채널 풀 안에서만 일어난다는 것입니다. anthropic/xxx를 요청했다고 해서 다른 회사의 모델로 전환하지는 않습니다 — 모델 간 교체는 출력 품질을 직접 바꾸므로, 이는 저희가 대신 결정할 수 없는 사안입니다.

오류 코드 빠른 조회 보기 →