Retries & Fallback
일시 장애는 자동 재시도, 프로바이더 장애는 자동 폴백 — 별도 설정 없이 모든 호출에 적용됩니다.
PleumRouter는 프로바이더 호출 실패를 에러 종류별로 분류해, 재시도할 가치가 있는 실패만 같은 프로바이더에서 재시도하고 그 외에는 즉시 다음 프로바이더로 폴백합니다. 여러 프로바이더가 서빙하는 모델은 후보를 가격순(또는 개인 라우팅 설정 순)으로 순회하므로, 한 프로바이더 장애가 요청 실패로 이어지지 않습니다. 전 과정이 자동이며 요청에 아무 것도 추가할 필요가 없습니다.
실패 분류 규칙#
실패한 시도는 다음 규칙으로 분류됩니다.
| 실패 유형 | 재시도 또는 폴백 동작 |
|---|---|
| 429 rate limit | 같은 프로바이더에서 재시도하되, 응답의 Retry-After 헤더(정수 초·HTTP 날짜 모두 지원)를 존중해 대기합니다. 대기 시간은 최대 10초로 캡되고, 헤더가 없으면 지수 백오프를 사용합니다. |
| 5xx · network | 일시 장애로 보고 같은 프로바이더에서 재시도합니다. 대기는 지수 백오프(0.5초부터 2배씩)에 ±10% 지터를 더해 동시 재시도 몰림을 완화합니다. |
| 401 · 403 | 키 문제라 같은 프로바이더 재시도는 의미가 없으므로 대기 없이 즉시 다음 프로바이더로 넘어갑니다. |
| 기타 4xx | 요청 자체 문제일 가능성이 높아 같은 프로바이더 재시도는 하지 않고, 다음 프로바이더로 1회 진행합니다(프로바이더별 파라미터 방언 차이로 회복될 수 있음). |
재시도 횟수: 단일 프로바이더 모델은 기본 2회 재시도(총 3회 시도), 멀티 프로바이더 모델은 기본 재시도 없이 다음 후보로 바로 넘어갑니다. 프로바이더 전환은 대기 없이 즉시 이뤄집니다. 이 값들은 운영 설정으로 조정됩니다.
폴백이 일어나면 응답의 provider 필드가 실제로 서빙한 프로바이더를 가리키며, 과금도 그 프로바이더의 단가 기준입니다(후보마다 단가가 다를 수 있습니다).
response after fallback
{
"id": "req-8f3a...",
"model": "gpt-4o",
"provider": "openai",
"choices": [{"message": {"role": "assistant", "content": "..."}}],
"usage": {"prompt_tokens": 120, "completion_tokens": 48}
}스트리밍 폴백#
스트리밍에서는 첫 델타(토큰)가 나가기 전의 실패만 다음 프로바이더로 무중단 폴백합니다. 같은 프로바이더 재접속 재시도도 델타가 0개인 동안에만 수행됩니다.
델타가 하나라도 클라이언트로 전송된 뒤 실패하면 폴백하지 않고 스트림이
error 이벤트(partial: true)로 종료되며, 이미 전송된 토큰은 과금됩니다(부분 과금). 중간에 다른 모델로 갈아타면 이중 전송·이중 과금 위험이 있어 의도적으로 폴백하지 않습니다.