Claude Code의 fallbackModel은 429 에러가 아닌 529 과부하(overload) 발생 시 최대 3개의 모델까지 재시도합니다. 4단계(settings.json + CLI)로 설정하고 게이트웨이가 승리하는 시점을 파악하세요.

4단계로 3단계 페일오버(Failover) 설정하기

Anthropic이 529 overloaded_error를 반환할 때, 설정되지 않은 Claude Code 세션은 동일한 모델을 재시도한 후 사용자에게 에러를 전달합니다. 페일오버 체인(fallback chain)은 이러한 막다른 길을 단계적 전환(downshift)으로 바꿔줍니다. 즉, Opus에서 과부하가 발생하면 Sonnet으로 재시도하고, Sonnet마저 사용할 수 없다면 Haiku로 전환합니다.

수행 가능한 작업

Claude Code가 순서대로 최대 3개의 백업 모델을 시도하도록 하여, 529 과부하 상황에서도 대화(turn)를 유지할 수 있습니다.

소요 시간

약 5분

필요 사항

Claude Code v2.1.197 이상 (Sonnet 5 별칭 사용을 위해), 나열된 모델들에 대한 계정 액세스 권한, 그리고 settings.json 수정 권한

전체 설정은 하나의 배열(array)로 구성됩니다:

{
  "model": "opus",
  "fallbackModel": ["sonnet", "haiku"]
...

이것은 3단계 체인입니다: opus가 기본(primary) 모델이며, sonnet과 haiku가 페일오버(fallback) 모델입니다. 이 가이드의 나머지 내용은 배열만으로는 명확하지 않은 부분들, 즉 어떤 에러가 실제로 이를 트리거하는지, 왜 429 에러는 트리거하지 않는지, 팀 전체에서 체인이 어떻게 동작하는지, 그리고 단일 계정 체인이 도움이 멈추는 지점이 어디인지에 대해 다룹니다.

이 설정을 마친 후 할 수 있는 것 (그리고 할 수 없는 것)

페일오버 체인은 국소적인 도구입니다. 이를 구축하기 전에 그 한계를 정확히 아는 것이 가치가 있습니다. 왜냐하면 이 도구가 해결하는 실패는, 이 도구가 해결하지 못하는 두 가지 실패와 매우 유사해 보이기 때문입니다.

페일오버 체인이 제공하는 기능은 다음과 같습니다:

• 일시적인 Anthropic 과부하(529 overloaded_error) 상황에서도 대화(turn)를 잃지 않고 생존합니다.
• 특정 모델을 사용할 수 없는 경우에도 작동을 유지합니다. 예를 들어, 설정에 고정되어 있지만 이후 은퇴(retired)된 모델의 경우입니다.
• 의도적으로 성능을 단계적으로 낮춥니다(downshift capability). 따라서 Opus에서 시작한 어려운 작업이 아예 중단되는 대신 Sonnet에서 완료될 수 있도록 합니다.

다음은 수행할 수 없는 작업입니다:

• 429 Rate Limit (속도 제한) 또는 사용량 제한(usage cap)을 통과하게 해줄 수는 없습니다. 이는 할당량(quota) 문제이며, 체인 내의 모든 모델은 동일한 계정 할당량을 사용하기 때문입니다.
• 다른 제공업체(provider)로 페일오버(Fail over)할 수 없습니다. 체인 요소들은 하나의 계정에 있는 Claude 모델들로 결정되므로, Anthropic 전체 서비스가 중단되면 체인도 함께 중단됩니다.
• 기본 모델(primary model)을 영구적으로 변경할 수 없습니다. 전환은 턴(turn) 단위로 이루어지며, 다음 메시지는 다시 기본 모델로 시작됩니다.

만약 반복되는 문제가 "과부하(overloaded)"가 아니라 "사용량 제한 도달(usage limit reached)"이라면, 페일오버 체인(fallback chain)은 잘못된 해결책입니다. Claude Code에서 rate limit reached 오류 발생 시에 관한 별도의 가이드를 참조하시고, 과부하 자체에 대한 API 레벨 버전은 Claude API error 529를 참조하세요.

결정 프레임: 이 설정을 사용해야 할 때 (그리고 사용하지 말아야 할 때)

사용해야 할 때

• 중간에 529 오류가 발생할 경우 전체 작업이 중단될 수 있는 무인(unattended) 또는 스크립트 환경(CI, 긴 에이전트 실행, 야간 작업 등)에서 Claude Code를 실행하는 경우.
• 할당량이 아닌 과부하가 주요 중단 원인인 유료 API 또는 높은 티어(high tier)를 사용하는 경우.
• 해당 턴을 완료하는 대가로 턴의 나머지 부분에서 품질 저하(quality downshift)를 감수할 수 있는 경우.

사용하지 말아야 할 때

• 중단 원인이 429 오류 또는 "사용량 제한 도달(usage limit reached)"인 경우. 이 경우 체인은 아무런 역할을 하지 못합니다. 대신 할당량이나 캐싱(caching)을 해결해야 합니다 (토큰 최적화 (token optimization)가 해결책입니다).
• 재현성(reproducibility)을 위해 모든 턴이 특정 모델에서 수행되어야 하는 경우. 실행 도중 Haiku로 조용히 모델이 전환되면, 이후 단계가 의존하는 출력 품질이 변할 수 있습니다.
• 제공업체 레벨의 회복탄력성(resilience)이 필요한 경우. 하나의 계정은 자기 자신으로 페일오버할 수 없습니다. 이를 위해서는 게이트웨이(gateway)가 필요합니다 (아래에서 다룸).

중단 규칙 (Stop rule)

과부하 시 단일 자동 백업만을 원한다면, 항목을 하나만 추가하고 끝내면 됩니다: "fallbackModel": ["sonnet"]. 3단계 체인은 Opus가 Sonnet과 동시에 부하를 받을 것으로 예상되는 경우(주로 플랫폼 전반의 장애가 발생할 때)에만 유효합니다.

시스템 요구 사항 (System Requirements)

현재 Anthropic API에서 세 가지 별칭(alias)과 그에 대응하는 모델은 다음과 같습니다:

위 표의 두 가지 세부 사항이 합리적인 체인을 구성하는 데 중요한 역할을 합니다. Sonnet 5는 2026년 8월 31일까지 MTok당 $2 / $10의 도입 가격(introductory pricing)을 적용하므로, 현재 중간 단계(middle tier)가 정가보다 저렴합니다. 또한 Haiku 4.5는 Opus 및 Sonnet이 지원하는 1M가 아닌 200K의 컨텍스트 창(context window)을 가지므로, 200K를 초과하는 긴 세션은 Haiku 단계에 담을 수 없습니다. 이를 염두에 두고 체인 순서를 정하십시오. Haiku는 품질 때문만이 아니라 용량(capacity) 문제로 인해 최후의 수단이 됩니다.

단계별 설정 (Step-by-Step Setup)

1단계: 기본 모델 및 버전 확인

claude --version
claude   # 그 다음 세션 내부에서 /status 실행

/status는 활성화된 모델을 보여줍니다. 만약 opus가 Opus 4.8로 해석되지 않거나, sonnet이 Sonnet 5가 아니라면 먼저 claude update를 실행하세요. 예상 결과: 2.1.197 이상의 버전과 인식 가능한 기본 모델.

2단계: 플래그를 사용하여 한 세션 동안 체인 테스트

설정을 영구적으로 저장하기 전에, CLI 플래그를 사용하여 체인을 테스트해 보세요. 이 플래그는 쉼표로 구분된 목록을 허용하며 저장된 모든 설정을 재정의(override)하므로, 실험하기에 가장 안전한 방법입니다.

claude --model opus --fallback-model sonnet,haiku

예상 결과: 세션이 Opus로 시작됩니다. 실제로 과부하(overload)가 발생하지 않는 한 페일오버(fallback)가 실행되는 것을 볼 수 없으며, 과부하가 발생하면 Claude Code가 전환된 모델의 이름을 명시하여 공지를 출력합니다.

3단계: settings.json에 체인(chain) 영구 저장하기

플래그(flag)가 의도대로 작동한다면, 모든 세션이 이를 상속받을 수 있도록 설정을 settings로 옮깁니다. 별칭(alias) 또는 전체 모델 ID(full model ID)를 모두 사용할 수 있습니다. 전체 ID를 사용하면 특정 버전을 고정할 수 있으며 별칭 변경 시에도 유지됩니다.

{
  "model": "opus",
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
...

예상 결과: 새로운 세션은 플래그 없이도 두 개의 모델로 구성된 페일오버 체인(fallback chain)과 함께 Opus로 시작됩니다. 단, --fallback-model 플래그를 사용하여 실행하는 세션에서는 해당 플래그가 우선권을 가집니다.

4단계: 정상 경로(happy path)가 아닌 트리거 조건(trigger conditions) 검증하기

요청에 따라 실제 529 에러를 인위적으로 만들어낼 수는 없으므로, 장애가 발생하기를 기다리는 대신 논리적으로 추론 가능한 부분들을 검증하십시오. 각 요소가 접근 가능한 모델로 해결되는지 확인하고, 어떤 상황에서 트리거가 작동하지 않는지를 이해해야 합니다. 체인이 제대로 읽혔는지 확인하기 위해 에러에 의존하지 마십시오. Claude Code는 시작 시점에 fallbackModel을 검증하지 않으므로(v2.1.208에서 확인됨), 잘못된 값이 입력되면 에러를 발생시키는 대신 조용히 무시됩니다. 마지막 지점인 '무엇이 트리거를 작동시키지 않는가'에 대부분의 설정 오류가 숨어 있으므로, 별도의 섹션으로 다룹니다.

무엇이 페일오버를 트리거하는가 (그리고 무엇이 그렇지 않은가)

이 표를 숙지하십시오. 페일오버는 가용성 실패(availability failures) 시에만 실행되며, 그 외의 모든 상황에서는 침묵을 유지합니다.

429 행은 사람들이 혼동하기 쉬운 부분입니다. Rate limit (속도 제한)은 할당량(quota)을 모두 소진했음을 의미하며, 체인 내의 모든 모델은 동일한 계정에 대해 비용을 청구하므로 Opus에서 Haiku로 전환한다고 해서 여유 공간(headroom)이 생기지는 않습니다. Claude Code는 이를 알고 있으며, 429 상황에서는 페일오버를 소모하는 것을 거부합니다. 만약 로그에 장애 발생 중에도 페일오버가 전혀 작동하지 않는 것으로 나타난다면, 해당 장애가 실제로 429인지 확인하십시오.

동일한 로직을 흐름도(flow)로 나타내면 다음과 같습니다:

flowchart TD
    A[모델 요청 (Model request)] --> B{응답 (Response)}
    B -->|529 / 사용 불가 (unavailable) / 재시도 불가능한 5xx| C{체인에 모델이 더 있는가?}
...

체인 순서(Chain Order) 선택하기

배열(array)의 순서는 Claude Code가 시도하는 순서이므로, 배열은 집합(set)이 아닌 우선순위 목록(priority list)입니다. 최적화하려는 대상에 따라 대부분의 경우를 커버하는 두 가지 기본 설정이 있습니다.

역량 우선 (Capability-first) (opus를 기본 모델로 두고 ["sonnet", "haiku"] 설정) 방식은 가용성이 허용하는 한 품질을 최대한 높게 유지하며, 두 개의 더 큰 모델이 동시에 과부하 상태일 때만 Haiku로 전환합니다. 성능 저하가 진정한 최후의 수단이어야 하는 대화형 작업(interactive work)에 사용하십시오.

비용 우선 (Cost-first) (sonnet을 기본 모델로 두고 ["haiku"]를 페일오버로 설정) 방식은 Opus를 전혀 사용하지 않습니다. 처리량(throughput)과 예측 가능한 지출이 성능의 한계치보다 더 중요한 CI 및 에이전트 루프(agent loops)에서 사용하십시오. 여기에는 하이브리드 라우팅 (hybrid routing) 논리가 적용됩니다. 대부분의 턴(turn)에는 Opus가 필요하지 않으므로, 단순히 긴 체인을 갖기 위해 Opus를 기본 모델로 설정하는 것은 일반적인 상황에서 비용을 낭비하는 것입니다.

한 가지 제약 사항이 두 가지 선호 사항보다 우선하며, 이는 놓치기 쉽습니다. 바로 컨텍스트 윈도우 (context window)입니다. Haiku 4.5는 200K 윈도우를 제공하는 반면, Opus 4.8과 Sonnet 5는 1M를 제공합니다. 이미 200K를 넘어선 세션은 Haiku 티어(tier)로 아예 전환될 수 없으므로, 긴 컨텍스트 작업 시에는 Haiku를 체인의 어디에 배치하더라도 사실상 체인에서 제외됩니다. 만약 세션이 정기적으로 대규모로 실행된다면, 체인을 1M 윈도우 티어에 유지하고, Opus와 Sonnet이 동시에 중단될 경우 컨텍스트가 조용히 잘리는 대신 해당 턴(turn)이 실패하도록 허용하십시오.

전환(Switch)이 어떻게 보이는가

페일오버 (fallback)는 결코 조용히 일어나지 않습니다. 하나가 작동하면, Claude Code는 트랜스크립트 (transcript)에 전환된 모델의 이름을 명시한 공지를 출력합니다. 전환은 턴 (turn) 단위로 범위가 지정되기 때문에, 세션이 조용히 Haiku로 안착하는 것이 아니라 다음 과부하 발생 시 해당 공지를 다시 보게 됩니다. 반대로, 설정 오류 (misconfiguration)는 조용히 발생합니다. 잘못된 fallbackModel 값은 경고 없이 무시되므로 (v2.1.208에서 확인됨), 고장 난 체인은 과부하가 발생하여 공백을 발견할 때까지 정상 작동하는 체인과 똑같이 보입니다. 체인이 실제로 활성화되어 있는지 확인하려면 시작 오류를 찾지 마십시오. 다음에 설명할 대로 JSON 실행의 modelUsage 필드를 통해 감사 (audit)하십시오.

JSON을 출력하는 비대화형 실행 (-p / --print)에서는 일반 텍스트 공지가 억제되므로, 기본 모델이 턴을 처리했다고 가정하지 말고 결과 메시지의 modelUsage 필드에서 실제로 응답한 모델을 읽으십시오. 이것이 사후에 체인이 얼마나 자주 무언가를 포착했는지, 그리고 어떤 티어가 부하를 흡수했는지를 감사하는 신뢰할 수 있는 방법입니다. 실제 장애 발생 시간 동안 체인이 한 번도 포착(catch)을 보여주지 않는다면, 해당 장애가 어떤 체인으로도 커버할 수 없는 429 오류였는지 다시 확인하십시오.

설정 중 흔히 발생하는 오류 (및 해결 방법)

병합되지 않는 (no-merge) 동작 방식은 대부분의 배열 (Array) 설정이 작동하는 방식과 정반대이므로 강조할 가치가 있습니다. 만약 사용자의 설정 (User settings)에서 정교한 3단계 체인을 조정해 두었더라도, 어떤 리포지토리 (Repo)가 자체적인 단일 모델 fallbackModel이 포함된 .claude/settings.json을 배포한다면, 해당 리포지토리가 완전히 우선권을 가지며 사용자의 체인은 경고 없이 폐기됩니다. 우선순위 (Precedence)는 관리형 설정 (Managed settings), 명령줄 플래그 (Command-line flags), 프로젝트 로컬 (Project-local), 프로젝트 (Project), 사용자 (User) 순으로 적용됩니다. 실제로 사용하고자 하는 체인을 해당 세션이 읽게 될 가장 높은 우선순위의 파일에 배치하십시오.

팀 / 다중 개발자 설정 (Team / Multi-Developer Configuration)

개발자 한 명의 경우, ~/.claude/settings.json에 fallbackModel을 설정하는 것으로 충분합니다. 팀 단위에서는 누가 체인을 소유하는지, 그리고 개인이 이를 재정의 (Override)할 수 있는지 여부가 중요한 질문이 됩니다.

팀 단위에서 중요한 두 가지 상호작용이 있습니다. 첫째, 개발자가 실행할 수 있는 모델을 제한하기 위해 availableModels를 함께 사용하는 경우, 허용 목록 (Allowlist) 외부에 있는 페일오버 (Fallback) 요소는 체인을 읽을 때 폐기됩니다. 따라서 강제된 체인과 허용 목록이 서로 일치해야 합니다. 둘째, 페일오버 체인은 병합되지 않기 때문에, 커밋된 프로젝트 체인은 해당 리포지토리 내에서 각 개발자의 개인 체인을 완전히 대체합니다. 이는 CI 및 공유 에이전트 (Shared agents)를 위해서는 보통 원하는 방식이지만, 개인 체인을 조정해 둔 개발자가 해당 리포지토리에서 작업하는 동안 이를 인지하지 못한 채 상실하게 된다는 것을 의미합니다. 설계에 의해 재정의되어

이는 CI(지속적 통합)를 더 저렴한 Sonnet 티어에 유지하면서, 과부하 시에는 Haiku로 페일오버(Failover)하고, 그 누구도 CI 작업을 Opus로 몰래 전환하는 것을 방지합니다.

고급: 게이트웨이를 통한 교차 제공업체(Cross-Provider) 페일오버