Skip to main content

​
📌 문제

일부 사용자는 Claude Code를 실행하는 동안 다음과 같은 오류를 겪습니다:
  • 400 ValidationException
  • Extra inputs are not permitted
  • cache_control.scope를 언급하는 오류
이러한 문제는 거의 항상 Claude Code의 실험적 베타 매개변수 때문에 발생하며, 이는 APIYI가 제공하는 공식 Amazon Claude API(AWS Claude / Bedrock) 채널에서 지원되지 않습니다.
이 가이드는 AWS Claude (Bedrock) 공식 채널을 통해 전달되는 요청에만 적용됩니다. 기본 Anthropic API 채널은 이러한 베타 매개변수를 지원하므로, 아래 변경 사항은 필요하지 않습니다.

​
✅ 해결 방법 (권장)

Claude Code의 실험적 베타 기능을 비활성화합니다.

​
옵션 1: settings.json 편집 (권장)

환경 변수를 Claude Code settings.json에 추가합니다:

​
옵션 2: 임시 적용 (현재 터미널 세션)

터미널에서 다음을 실행합니다:
그다음 Claude Code를 다시 시작합니다.
옵션 2는 현재 터미널 창에만 적용되며 닫으면 사라집니다. 영구적으로 적용하려면 옵션 1 또는 옵션 3을 사용합니다.

​
옵션 3: 영구 적용 (권장)

사용 환경에 따라 셸 설정 파일에 변수를 기록합니다.

​
Mac / Linux (bash)

​
Mac (zsh, 기본값)

​
Windows (PowerShell)

그다음 터미널을 다시 시작합니다.

​
🔍 이 현상이 발생하는 이유(기술적으로 살펴보면)

Claude Code는 기본적으로 다음과 같은 여러 beta 기능을 활성화합니다.
  • cache_control
  • 확장된 tool 필드
  • scope 같은 추가 매개변수
이러한 매개변수는 다음과 같습니다.
  • 👉 네이티브 Anthropic API에서 지원됩니다
  • 👉 하지만 AWS Bedrock Claude에서는 유효하지 않은 필드로 거부되어 HTTP 400이 반환됩니다
이 스위치를 끄면 다음과 같습니다.
  • ✔ 요청이 표준 구조로 되돌아갑니다
  • ✔ AWS Claude와의 완전한 호환성 확보

​
🚨 이 변수가 필요한 경우

다음 중 하나라도 해당된다면, 이 변수를 설정하는 것을 강력히 권장합니다:
  • AWS Bedrock Claude와 함께 Claude Code를 사용하는 경우
  • 서드파티 프록시(API 게이트웨이 또는 포워딩 서비스)를 거치는 경우
  • 400 / ValidationException 오류가 보이는 경우
참고 자료:
  • Claude 공식 문서 — 환경 변수: code.claude.com/docs/en/env-vars
  • 관련 이슈: github.com/anthropics/claude-code/issues/21676

​
🔎 모델이 속한 그룹 확인하기

주어진 모델을 어떤 그룹에서 사용할 수 있는지 잘 모르시겠습니까? 모델 과금 페이지에서 확인할 수 있습니다: APIYI 모델 과금 페이지를 열고 모델 이름을 검색하여 사용할 수 있는 그룹을 확인하십시오. 예를 들어, ClaudeCode 그룹은 최신 Claude 모델 시리즈와 별도로 구성된 glm-5.1 및 qwen3.7-max를 지원합니다.

​
💡 아직도 작동하지 않습니까?

수정 사항을 적용한 후에도 오류가 지속되면 다음을 확인하십시오.
  • 환경 변수가 실제로 적용되었는지 확인하십시오(echo $CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS를 실행하고 1가 출력되는지 확인하십시오)
  • 실제로 AWS Claude (Bedrock) 채널을 사용하고 있는지 확인하십시오
  • 설정을 변경한 후 터미널 또는 IDE를 다시 시작했는지 확인하십시오

​
📞 지원

여전히 해결되지 않는다면, 더 자세히 살펴볼 수 있도록 다음 정보를 보내주십시오.
  • 오류 스크린샷
  • 요청 로그(Request ID)
  • 사용 중인 모델 이름
문제를 함께 추적해 드리겠습니다.