레이트리밋엔 걸리지 않는다: 에이전트 하네스의 모델 폴백 라우팅 설계

거부는 에러가 아니라 "성공 응답"입니다

앤트로픽 Claude API에서 세이프티 분류기가 요청을 거절하면 응답은 4xx·5xx가 아니라 stop_reason: "refusal"을 담은 정상 HTTP 200으로 돌아옵니다. stop_details.category는 cyber·bio·frontier_llm·reasoning_extraction·general_harms 5개 정책 영역 중 하나를 알려줍니다. 2026년 9월 기준 바이오·프런티어 모델·추론 노출 3개 카테고리는 출력이 0토큰이어도 과금되고, 나머지 범주는 과금되지 않습니다. 에러율·5xx 경보로 하네스를 감시하던 팀은 이 성공 응답을 그냥 통과시킵니다.

서버사이드 폴백이 덮는 범위는 생각보다 좁습니다

fallbacks 파라미터를 "default"로 두면 앤트로픽이 거부 카테고리별로 권장하는 모델로 같은 요청이 한 번 더 실행되고, 직접 최대 3개 모델을 순서대로 지정할 수도 있습니다. 지정 모델은 요청 모델의 허용 대상(allowed_fallback_models)에 속해야 하며, 베타 헤더 날짜가 2026-07-01이 아니라 2026-06-01이면 "default"는 거부됩니다. 다만 이 폴백은 세이프티 거부에만 걸립니다 — 레이트리밋·과부하·서버 오류는 보낸 그대로 돌아옵니다. 한번 폴백 모델로 넘어간 대화는 조직 단위로 약 1시간만, 그것도 best-effort로 그 모델에 고정됩니다.

설계에서 운영까지: 모델 폴백 라우팅 체크리스트

기획 단계에서 숫자로 선을 긋습니다. 거부 발생 후 폴백 모델이 실제로 응답까지 도달하는 폴백 성공률을 95% 이상으로 잡고, 적용 범위는 메인 호출뿐 아니라 서브에이전트·도구 호출 경로까지 100% 커버리지로 둡니다. 배치(Message Batches) 경로는 fallbacks 자체가 거부되므로 거부 수집 후 1시간 안에 재제출하는 별도 SLA가 필요합니다.

가장 조용히 새는 실패 지점은 폴백 모델 자체가 레이트리밋·과부하 상태일 때입니다. 이때 폴백 시도는 생략되고 원래 거부가 그대로 반환되며, stop_details.recommended_model은 보장이 아니라 힌트일 뿐입니다. 체인에 올린 모델의 레이트리밋을 평소 거부량보다 넉넉히 잡지 않으면 트래픽이 몰리는 시점에 보호망이 먼저 무너집니다. 두 번째는 거부당한 모델에 같은 요청을 재전송하는 실수이고, 세 번째는 공유 플래그 같은 앰비언트 상태로 폴백 여부를 관리하는 습관입니다 — 설정과 어긋난 요청은 보호 대상에서 조용히 빠지므로, 폴백은 매 요청에 붙는 속성으로 선언해야 합니다.

네 번째 공백은 서버사이드 폴백을 썼으니 장애 대응이 끝났다고 보는 판단입니다. 레이트리밋·과부하·서버 오류는 폴백 대상이 아니라 별도의 재시도·백오프가 그대로 필요하고, 아마존 베드록·버텍스AI·마이크로소프트 파운드리처럼 서버사이드 폴백이 없는 플랫폼에서는 SDK 미들웨어로 같은 보호를 구현해야 합니다.

운영 체크리스트는 거부를 5xx와 별개 신호로 계측하는 데서 시작합니다. 거부 이벤트 건수와 응답의 usage.iterations에 찍히는 fallback_message 건수를 각각 집계해 격차가 벌어지면 경보를 겁니다. 배포 파이프라인에는 베타 헤더 날짜를 고정값으로 검증하는 단계를 넣어 날짜 하나가 틀려 fallbacks 전체가 400으로 떨어지는 사고를 미리 걸러내고, 서브에이전트·도구 호출 구간은 메인 호출과 따로 점검합니다 — 그 안의 모델 호출은 fallbacks 설정을 물려받지 않습니다.

지속 개선은 거부 카테고리 분포를 매주 모아 과금 대상 범주의 비중 변화를 비용 대시보드에 바로 연결하는 작업입니다. 스티키 라우팅이 1시간을 넘기는 장시간 대화는 재거부 가능성을 가정하고 모니터링을 유지하며, 디폴트 라우팅에서 명시적 모델 리스트로 옮긴 요청은 전환 근거를 변경 로그에 남겨 다음 모델 교체 때 참고합니다.

한눈에 보는 적용 포인트

서버사이드 폴백은 세이프티 거부 전용 안전망이며 레이트리밋·과부하·서버 오류까지 막아주지 않습니다. 폴백 성공률 95% 이상과 서브에이전트까지 포함한 적용 범위 100%를 목표로 걸고, 거부와 폴백 서빙을 별도 신호로 계측하면서 베타 헤더 날짜·허용 모델 리스트를 배포 전에 검증하면 이 베타 기능이 바뀌어도 하네스의 장애 대응 설계는 흔들리지 않습니다.

참고 링크

Refusals and fallback — Claude Platform Docs

Fallback credit — Claude Platform Docs