Retries & Fallback

PleumRouter는 프로바이더 호출 실패를 에러 종류별로 분류해, 재시도할 가치가 있는 실패만 같은 프로바이더에서 재시도하고 그 외에는 즉시 다음 프로바이더로 폴백합니다. 여러 프로바이더가 서빙하는 모델은 후보를 가격순(또는 개인 라우팅 설정 순)으로 순회하므로, 한 프로바이더 장애가 요청 실패로 이어지지 않습니다. 전 과정이 자동이며 요청에 아무 것도 추가할 필요가 없습니다.

실패 분류 규칙#

실패한 시도는 다음 규칙으로 분류됩니다.

429 (rate limit) — 같은 프로바이더에서 재시도하되, 응답의 Retry-After 헤더(정수 초·HTTP 날짜 모두 지원)를 존중해 대기합니다. 대기 시간은 최대 10초로 캡되고, 헤더가 없으면 지수 백오프를 사용합니다.

5xx·네트워크 오류·깨진 200 응답 — 일시 장애로 보고 같은 프로바이더에서 재시도합니다. 대기는 지수 백오프(0.5초부터 2배씩)에 ±10% 지터를 더해 동시 재시도 몰림을 완화합니다.

401 / 403 — 키 문제라 같은 프로바이더 재시도는 의미가 없으므로 대기 없이 즉시 다음 프로바이더로 넘어갑니다.

그 외 4xx (400·404·422 등) — 요청 자체 문제일 가능성이 높아 같은 프로바이더 재시도는 하지 않고, 다음 프로바이더로 1회 진행합니다(프로바이더별 파라미터 방언 차이로 회복될 수 있음).

재시도 횟수: 단일 프로바이더 모델은 기본 2회 재시도(총 3회 시도), 멀티 프로바이더 모델은 기본 재시도 없이 다음 후보로 바로 넘어갑니다. 프로바이더 전환은 대기 없이 즉시 이뤄집니다. 이 값들은 운영 설정으로 조정됩니다.

폴백이 일어나면 응답의 provider 필드가 실제로 서빙한 프로바이더를 가리키며, 과금도 그 프로바이더의 단가 기준입니다(후보마다 단가가 다를 수 있습니다).

{
  "id": "req-8f3a...",
  "model": "gpt-4o",
  "provider": "openai",
  "choices": [{"message": {"role": "assistant", "content": "..."}}],
  "usage": {"prompt_tokens": 120, "completion_tokens": 48}
}

스트리밍 폴백#

스트리밍에서는 첫 델타(토큰)가 나가기 전의 실패만 다음 프로바이더로 무중단 폴백합니다. 같은 프로바이더 재접속 재시도도 델타가 0개인 동안에만 수행됩니다.