장애 대비 폴백
프로바이더가 오류를 돌려주거나, 응답을 시작하지 못하거나, 정한 시간 안에 첫 바이트가 오지 않으면 미리 정한 다음 모델로 같은 요청을 다시 보냅니다. 조직 단위 정책으로 켜 두거나, 요청마다 models 배열로 지정합니다.
동작 순서
한 요청 안에서 일어나는 일 요청한 모델(1순위)로 프로바이더를 호출합니다. 일시적인 프로바이더 오류에 대한 재시도는 여기서 먼저 일어납니다. 트리거에 해당하는 실패가 나면 폴백 체인의 다음 모델로 넘어갑니다. 체인은 요청의 models 배열이 있으면 그것을, 없으면 조직 폴백 정책의 fallback_models 를 씁니다. 각 후보는 조직 차단 모델(그룹 정책 포함)·API 키 허용 목록·차단 프로바이더 검사를 통과해야 합니다. 통과하지 못한 후보는 오류 없이 건너뜁니다. 어느 후보가 답하면 그 모델로 과금하고, 응답 헤더에 원래 모델과 사유를 남깁니다. 감사 로그와 라우팅 분석에도 시도 이력이 남습니다. 모두 실패하면 1순위 모델의 마지막 오류를 그대로 돌려주고 시도한 후보 목록을 헤더로 알려 줍니다. 스트리밍에서는 첫 바이트 전까지만 폴백은 클라이언트에 아무 바이트도 보내기 전에만 일어납니다. 스트리밍 중간에 프로바이더가 끊기면 지금처럼 그 시점의 오류가 전달됩니다. 지연 임계값은 스트리밍 요청에서는 응답 헤더(첫 바이트)가 도착할 때까지, 비스트리밍 요청에서는 응답 본문 전체가 도착할 때까지 잽니다. 헤더 뒤 첫 본문 조각의 지연은 잡지 않습니다. 이 임계값은 첫 시도(직접 호출이든 스마트 라우팅으로 고른 프로바이더든), 키 재시도, 그리고 각 폴백 후보에 같은 방식으로 적용됩니다.
조직 폴백 정책
설정 › 모델 접근 정책 › 장애 대비 폴백 · owner 전용 콘솔 대신 API로 다루려면 GET/PATCH /api/web/organizations/fallback-policy (콘솔 세션·owner)를 씁니다. 전사에 속한 그룹이면 최고 관리자가 「모든 그룹에 적용」( push_to_children )으로 같은 정책을 내려 줄 수 있고, 이후 그룹이 자기 값으로 바꿀 수 있습니다. 자세한 구조는 엔터프라이즈 조직 관리 를 보십시오.
요청마다 지정하기 — models 배열
OpenRouter와 같은 확장 필드. 다른 프로바이더로는 전달되지 않습니다 models 의 첫 항목이 1순위, 나머지가 순서대로 폴백 체인입니다. model 을 함께 보내면 그것이 1순위이고 models 는 체인만 채웁니다. 요청에 배열이 있으면 조직 정책의 fallback_models 대신 쓰이고, 트리거(상태 코드·타임아웃·지연 임계값)는 조직 정책 값을 따릅니다. cURL Python Node.js
응답 헤더
폴백이 일어났는지, 왜 일어났는지 확인하는 방법 헤더 값
적용 범위와 스마트 라우팅과의 관계
적용 엔드포인트: POST /v1/chat/completions (스트리밍 포함). Messages API 지원 여부는 Messages API 문서 의 안내를 따릅니다. 실시간 대화·오디오·이미지·동영상에는 적용되지 않습니다. 스마트 라우팅( bizrouter/route )은 자기 정책의 fallback_models 와 후보 순위를 씁니다. 이 문서의 조직 폴백 정책은 모델 코드를 직접 지정한 요청에 적용됩니다. 폴백으로 답한 요청의 요금은 실제로 답한 모델 기준입니다. 1순위 모델의 실패 시도는 과금되지 않습니다. 후보가 차단 모델·허용 목록 밖·차단 프로바이더면 조용히 건너뜁니다. 체인에 남는 후보가 없으면 폴백 없이 원래 오류가 그대로 옵니다. 성공을 보장하지 않습니다 폴백은 프로바이더 장애의 영향을 줄이는 장치입니다. 지연 임계값을 너무 낮게 잡으면 정상 응답도 끊고 다음 모델로 넘어가 비용과 지연이 늘 수 있습니다. 모델의 평소 첫 바이트 시간을 라우팅 분석에서 확인한 뒤 여유를 두고 정하십시오. 기존 동작은 그대로 조직 정책을 켜지 않고 models 배열도 보내지 않으면 지금과 똑같이 동작합니다. 일시적인 프로바이더 오류에 대한 재시도는 폴백과 무관하게 항상 일어납니다.
enabled boolean 조직 폴백 정책을 켭니다. 꺼져 있어도 요청의 models 배열은 동작합니다. fallback_models string[] (0~5) 순서대로 시도하는 대체 모델 코드. 조직에서 차단된 모델은 저장할 수 없습니다. on_status_codes number[] 이 상태 코드를 프로바이더가 돌려주면 다음 후보로 넘어갑니다. 허용 값: 408·429·500·502·503·504·529. 기본값은 전부. on_timeout boolean 연결·읽기 타임아웃과 전송 오류에서도 넘어갑니다. 기본 true. latency_threshold_ms number | null 지연 임계값(500~120000ms). 스트리밍은 응답 헤더(첫 바이트)까지, 비스트리밍은 응답 본문 전체가 도착할 때까지 잽니다. 이 시간을 넘기면 시도를 끊고 다음 후보로 갑니다. null이면 끔. x-bizrouter-routed-model 실제로 답한 모델 코드(기존 헤더) x-bizrouter-fallback-from 원래 요청한 모델 코드. 폴백이 일어난 응답에만 붙습니다. x-bizrouter-fallback-reason status_503 처럼 상태 코드, timeout, latency_threshold 중 하나 x-bizrouter-fallback-attempted 전체 후보가 실패해 오류를 돌려줄 때, 시도한 모델 코드 목록(쉼표 구분)