AWS Bedrock Claude 400 오류: 메시지별 원인과 해결 순서

AWS Bedrock으로 Claude를 호출하다 400 오류가 나면 오류 코드와 메시지 전체를 먼저 확인하세요. ValidationException의 알 수 없는 필드 오류와 잘못된 모델 ID 오류는 고칠 곳이 다릅니다. ServiceQuotaExceededException도 HTTP 400으로 반환될 수 있으므로, 400을 모두 JSON 형식 문제로 판단해서는 안 됩니다. AWS InvokeModel 오류 정의에 두 예외의 의미가 구분되어 있습니다.

Claude Code에서 베타 관련 필드를 거부한다면 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1이 도움이 될 수 있습니다. 하지만 모델 ID, 추론 프로필, 리전, 데이터 보관 정책 오류까지 해결하는 설정은 아닙니다. 먼저 아래 표에서 자신의 오류 메시지와 맞는 항목을 찾은 다음, 해당 부분만 바꿔 다시 확인하는 편이 빠릅니다.

이 글은 2026년 9월 21일에 확인한 공식 문서를 기준으로 합니다. 코드 예제는 문서에 맞춰 구성했으며 실제 AWS 계정에서 추론 호출을 실행한 결과는 아닙니다.

오류 메시지에서 고칠 곳 찾기

로그에는 HTTP 상태 코드와 함께 Error.Code, Error.Message, 요청 ID를 남기세요. Claude Code라면 클라이언트 버전과 /status에 표시되는 제공자도 확인합니다. 같은 “Claude 호출”이라도 AWS SDK 직접 호출인지, Anthropic 호환 엔드포인트인지, 중간 게이트웨이를 거치는지에 따라 요청 규격이 달라집니다.

AWS는 ValidationException의 원인으로 요청 본문뿐 아니라 모델·리전, API 선택, 가드레일 설정, 일부 호출 권한 문제도 안내합니다. 따라서 400이라는 이유만으로 IAM 문제를 배제하거나, 반대로 모든 문제를 해결하려고 권한을 넓히는 방식은 적절하지 않습니다. AWS ValidationException 해결 안내에서 실제 문구에 맞는 항목을 확인하세요.

먼저 API와 요청 본문을 맞추기

호출 메서드나 URL이 정해지면 그 규격에 맞는 본문 하나만 사용합니다. 인터넷에서 찾은 예제의 max_tokens, maxTokens, anthropic_version을 한 본문에 섞으면 정상 필드도 다른 API에서는 거부될 수 있습니다.

마지막 방식은 bedrock-runtime과 bedrock-mantle에 문서화되어 있습니다. 따라서 “Bedrock에서는 언제나 JSON에 anthropic_version을 넣는다”는 설명은 맞지 않습니다. 외부 게이트웨이 URL을 사용한다면 그 게이트웨이가 공개한 규격까지 확인해야 합니다. AWS Anthropic 호환 Messages API 문서

아래 두 예제 중 실제 사용하는 방식 하나를 골라 진단용으로 사용하세요. AWS_REGION과 BEDROCK_MODEL_ID에는 자신의 계정과 리전에서 호출 가능한 값을 지정해야 합니다. 인증 정보는 기존 AWS SDK 인증 구성을 사용하며 코드에 키를 넣지 않습니다.

Converse로 호출하는 경우

선택 옵션 없이 텍스트 한 줄만 보내면 오류 범위를 줄일 수 있습니다. Converse의 출력 토큰 필드는 inferenceConfig 안의 maxTokens입니다. system을 넣을 때는 messages의 역할로 추가하지 않고 별도 배열을 사용합니다. Converse 요청 규격

python
import os
import boto3
from botocore.exceptions import ClientError

client = boto3.client(
    "bedrock-runtime",
    region_name=os.environ["AWS_REGION"],
)

try:
    response = client.converse(
        modelId=os.environ["BEDROCK_MODEL_ID"],
        messages=[{
            "role": "user",
            "content": [{"text": "안녕하세요. 한 문장으로 답해주세요."}],
        }],
        inferenceConfig={"maxTokens": 128},
    )
    print(response["output"]["message"])
except ClientError as exc:
    error = exc.response.get("Error", {})
    metadata = exc.response.get("ResponseMetadata", {})
    print({
        "code": error.get("Code"),
        "message": error.get("Message"),
        "http_status": metadata.get("HTTPStatusCode"),
        "request_id": metadata.get("RequestId"),
    })
    raise

이 예제가 성공하면 연결·모델 선택·기본 요청은 동작한다는 단서가 됩니다. 그렇다고 도구, 이미지, 가드레일까지 모두 호환된다는 뜻은 아닙니다. 원래 요청의 선택 항목을 하나씩 복원해 처음 실패하는 항목을 찾으세요.

InvokeModel로 호출하는 경우

Claude Messages의 네이티브 InvokeModel 본문에는 anthropic_version: "bedrock-2023-05-31"과 max_tokens를 사용합니다. Converse의 inferenceConfig나 예전 Text Completions의 max_tokens_to_sample을 섞지 마세요. Claude Messages 요청 필드

python
import json
import os
import boto3

client = boto3.client(
    "bedrock-runtime",
    region_name=os.environ["AWS_REGION"],
)

body = {
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": 128,
    "messages": [{
        "role": "user",
        "content": [{"type": "text", "text": "안녕하세요."}],
    }],
}

response = client.invoke_model(
    modelId=os.environ["BEDROCK_MODEL_ID"],
    contentType="application/json",
    accept="application/json",
    body=json.dumps(body),
)
print(json.loads(response["body"].read()))

additionalModelRequestFields는 Converse에서 지원되는 모델별 확장 필드를 넣는 자리입니다. 거부된 필드를 아무거나 그 안으로 옮긴다고 지원되지 않던 기능이 활성화되지는 않습니다. 프롬프트 관리 ARN을 사용하는 요청에는 별도의 필드 제한도 있으므로 일반 모델 호출 예제를 그대로 적용하기 전에 해당 제약을 확인해야 합니다.

모델 ID에 접두사를 붙이기 전에 확인할 것

invalid model identifier가 보이면 엔드포인트, 리전, 모델 ID 또는 추론 프로필 ID를 한 묶음으로 확인하세요. 모델 이름이 맞아 보이더라도 해당 호출 방식에서 받을 수 없는 ID이거나 현재 리전에서 사용할 수 없는 값일 수 있습니다.

on-demand throughput isn’t supported라는 메시지는 지원되는 추론 프로필 ID나 ARN이 필요한 경우를 가리킵니다. 이때 임의로 us. 또는 global.을 붙이는 대신 현재 계정·리전에서 사용할 수 있는 프로필을 확인해야 합니다. 모델 자체가 없는 리전, 계정 이용 조건, IAM 권한 문제까지 접두사 하나로 해결되지는 않습니다.

Claude Code는 지리적 추론 프로필 접두사를 선호합니다. 공식 문서에 따르면 프로필 검색을 할 수 없는 환경에서는 가용성을 확인하지 못한 채 접두사를 적용할 수 있고, 그 결과 400이 발생할 수 있습니다. ANTHROPIC_BEDROCK_REGION_PREFIX는 v2.1.224 이상에서 사용할 수 있는 선택 설정이지만, 지정한 프로필의 사용 가능성을 보장하는 기능은 아닙니다. 명시적인 프로필 ID나 ARN을 대체하는 만능 설정으로 사용하지 마세요. Claude Code의 Bedrock 모델·프로필 설정

특히 Mantle을 사용한다면 구분이 더 중요합니다. Invoke 방식에서 쓰던 us.anthropic.* 같은 추론 프로필 ID를 Mantle의 모델 ID로 그대로 사용할 수 없습니다. Mantle은 자체 anthropic.* 모델 ID를 사용합니다. Claude Code의 /status로 현재 제공자를 확인하고, 의도한 연결 방식의 공식 모델 목록을 기준으로 값을 선택하세요.

Claude Code의 베타 필드가 거부될 때

오류가 베타 헤더나 베타 도구 필드를 가리킨다면 다음 설정으로 실험 기능을 제외한 실행을 시도할 수 있습니다. 아래 명령은 macOS·Linux 계열 셸 기준입니다.

bash
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

이미 실행 중인 Claude Code에는 셸의 새 환경 변수가 자동 반영되지 않습니다. 작업을 저장한 뒤 기존 프로세스를 종료하고, 변수를 설정한 같은 셸에서 다시 시작하세요. IDE에서 실행한다면 IDE나 실행 구성에서 전달하는 환경도 확인해야 합니다.

이 설정은 Anthropic 전용 베타 헤더와 베타 도구 스키마 필드를 제거하지만, 표준 name, description, input_schema, cache_control은 유지합니다. 즉, 프롬프트 캐시를 모두 끄는 설정은 아닙니다. 기본적으로 MCP 도구 검색도 비활성화되어 도구를 미리 불러오며, v2.1.227 이상에서는 관리형 설정으로 도구 검색을 유지할 수 있습니다. 공식 환경 변수 설명

게이트웨이가 anthropic-beta 헤더는 누락하고 베타 전용 본문 필드는 그대로 전달하는 경우에도 오류가 날 수 있습니다. 상위 서비스가 해당 기능을 지원한다면 헤더와 본문을 일관되게 전달하도록 수정하고, 지원하지 않는다면 그 기능을 사용하지 않는 쪽으로 맞춰야 합니다. 모든 Bedrock 베타 기능이 항상 금지된다고 판단할 근거는 아닙니다. Claude Code의 추가 필드 오류 안내

설정 후에도 같은 오류가 나면 claude --version과 전체 메시지를 다시 확인하세요. 과거 특정 버전의 장애 보고만 보고 현재 클라이언트를 곧바로 다운그레이드하거나, 모델 ID 문제에 베타 설정을 계속 바꿔 적용할 필요는 없습니다.

생각 모드와 대화 기록은 오류가 지목할 때 조정하기

생각 모드 관련 400은 현재 모델이 요구하는 모드와 요청 옵션을 맞춰야 합니다. 일반적인 확장 사고에서는 budget_tokens를 max_tokens보다 작게 설정하지만, interleaved thinking에는 별도 예외가 있습니다. 또한 AWS가 현재 안내하는 Fable 5·5.1 및 Mythos 5·5.1은 enabled와 disabled를 거부하고 adaptive thinking을 사용합니다. 따라서 “생각 모드를 끄면 해결된다”거나 하나의 예산 규칙을 모든 모델에 적용하는 조언은 안전한 진단법이 아닙니다. AWS 확장 사고 문서

오류가 tool_use, tool_result, thinking 블록의 불일치를 가리킨다면 대화 기록 문제를 따로 확인합니다. Claude Code 공식 안내는 문제가 생긴 턴 이전으로 /rewind하거나 Esc를 두 번 눌러 돌아가는 방법을 제시합니다. 이 조치는 기록 불일치에 적용하는 것이며, 모델 ID나 계정 정책 오류 때문에 대화 전체를 지울 이유는 없습니다. 도구·생각 블록 불일치 해결 안내

데이터 보관 정책 오류는 계정 설정부터 확인하기

오류 메시지가 데이터 보관 모드를 명시한다면 요청 본문만 바꿔서는 해결되지 않을 수 있습니다. Bedrock Runtime은 모델이 요구하는 보관 모드와 계정 설정이 맞지 않을 때 ValidationException을 반환할 수 있습니다.

2026년 9월 21일에 확인한 AWS 데이터 보관 문서는 새 설정에 aws_review를 사용하도록 안내합니다. 기존 값인 provider_data_share는 이름과 달리 현재 콘텐츠를 모델 제공자에게 전송하지 않습니다. 현재 문서에 지정된 Fable 모델의 검토는 AWS 내부에서 이루어지며 보관 기간은 최대 30일입니다. 예전 글의 “Anthropic에 데이터를 공유해야 한다”는 설명을 그대로 적용하면 현재 동작을 오해할 수 있습니다.

설정은 리전별이며, Bedrock Runtime에서는 프로젝트 단위가 아닌 계정 범위에 적용됩니다. 명시적으로 승인된 ZDR 계정은 특정 모델에서 none을 허용받을 수도 있으므로, 모델별 조건과 실제 승인을 확인해야 합니다. inherit나 기본값이라는 이유만으로 무조건 제로 데이터 보관이라고 볼 수는 없습니다.

이 경우에는 관리자에게 오류 전문, 호출 리전, 모델 ID, 요청 ID를 전달하고 유효한 보관 모드를 확인하세요. 오류를 없애기 위해 계정 전체의 보관 정책에 즉시 동의하거나 IAM 권한을 일괄 확대하는 명령을 실행하지 않는 것이 좋습니다. 조직의 데이터 취급 조건에 맞는지 먼저 판단해야 합니다.

수정한 뒤에는 같은 조건으로 한 번 확인하기

원인을 좁혔다면 관련 설정 하나를 바꾸고 같은 최소 요청으로 결과를 비교합니다. 성공하면 실제 요청의 시스템 지시문, 도구, 이미지, 생각 모드, 가드레일을 필요한 순서대로 하나씩 되돌립니다. 어떤 항목을 추가했을 때 오류가 다시 나는지 남기면 지원팀에도 재현 조건을 명확하게 전달할 수 있습니다.

잘못된 필드가 확인된 ValidationException을 같은 본문으로 계속 재시도해도 입력은 고쳐지지 않습니다. 반면 ServiceQuotaExceededException은 AWS 문서가 나중에 다시 요청할 수 있다고 안내하는 할당량 오류입니다. 429인 ThrottlingException과도 구분해 오류별로 대응해야 합니다. 재시도와 모델 전환을 설계하고 있다면 LLM API 재시도와 대체 모델 선택 기준, 호출 제한이 명시되었다면 Claude API 사용량 제한 오류 안내를 함께 참고하세요.

최소 요청도 실패하면 지원 요청에 다음 정보를 포함하면 됩니다.

• 발생 시각과 리전, 사용한 API 또는 엔드포인트 종류
• 모델 ID 또는 추론 프로필 ID와 Claude Code·SDK 버전
• HTTP 상태 코드, 오류 코드, 전체 오류 메시지, 요청 ID
• 민감한 내용을 제거한 최소 요청과 실제로 변경한 항목

공유 전에는 API 키, 인증 헤더, 프롬프트의 개인정보를 제거하세요. 오류 메시지에도 요청 내용이 들어갈 수 있으므로 로그 전체를 그대로 공개하지 말고 필요한 부분을 확인해 전달합니다.