Claude API 2026-10-21: 3년 만의 신규 버전, 샘플링 파라미터 포함 시 400 오류

TokenPost·opormid·AI Weekly · ax-trend 이슈 #3486 · 2026-10-21 발표

Claude API 2026-10-21 — 3년 만의 신규 버전, 샘플링 파라미터 전송 시 400 오류
개요 — 3년 만의 Claude API 신규 버전, 샘플링 파라미터를 보내면 400 오류가 된다

기본값을 넣어도 400이 된다

Anthropic이 2026년 10월 21일 Claude API의 새 버전 2026-10-21을 출시했습니다. 공식 API 버전이 새로 나온 것은 2023-06-01 이후 3년 만입니다. 핵심 변경은 하나입니다. 새 버전에서는 Messages API와 Message Batches API 요청에 temperature, top_p, top_k가 포함되면 400 오류를 반환합니다. 기본값을 그대로 넣어도 오류가 납니다. 값을 바꾸지 않았다고 안전한 것이 아닙니다. 필드 자체가 없어야 합니다.

400을 만드는 조건은 샘플링 파라미터만이 아닙니다. document 블록을 assistant 메시지에 직접 넣어도 400입니다. 문서 블록은 user 메시지에 넣어야 합니다. user 턴의 text 블록에 비어 있지 않은 citations 배열이 있어도 400입니다. 허용되는 형태는 {"citations": {"enabled": true}}뿐입니다. 세 조건 모두 "예전에는 되던 요청"이 "새 버전에서는 거부되는 요청"으로 바뀐 경우입니다.

# 새 버전에서 400이 되는 요청
POST /v1/messages
anthropic-version: 2026-10-21
{ "model": "...", "temperature": 1.0, "messages": [...] }  # 기본값이어도 400

# 허용되는 citations 형태
{ "citations": { "enabled": true } }

다행히 탈출구는 열려 있습니다. 기존 버전 2023-06-01은 deprecated되지 않았습니다. 비기본 샘플링 값이 꼭 필요한 팀은 구 버전을 계속 쓸 수 있습니다. 다만 구 버전에 머무는 것은 유예이지 해결이 아닙니다. 새 버전이 기본값이 되는 시점은 결국 옵니다.

버전은 모델 이름이 아니다

이 버전 식별자가 가리키는 것은 모델이 아니라 API 동작 방식입니다. Claude 4.7 이후 모델은 이미 기본 샘플링 값만 허용하고 있었습니다. 이번 버전은 그 동작을 API 레벨로 공식화한 것입니다. 모델을 바꾸지 않아도, 버전 헤더를 바꾸는 순간 동작이 바뀝니다. Anthropic은 앞으로 버전을 더 자주 내놓아, 호환되지 않는 변경을 새 모델이 강제하기 전에 개발자가 대응할 수 있게 하겠다고 밝혔습니다.

SDK와 CLI도 함께 메이저 버전이 올랐습니다. 새 SDK와 ant CLI가 기본으로 2026-10-21을 사용합니다. SDK를 메이저 버전으로 올리는 순간, temperature를 넣던 코드는 400으로 깨집니다. CI에 SDK 버전을 pin하지 않은 팀이 가장 먼저 맞습니다.

구성 요소새 메이저 버전
Python SDK2.0.0
TypeScript SDK1.0.0
C# SDK13.0.0
Go SDK2.0.0
Java SDK3.0.0
PHP SDK1.0.0
Ruby SDK2.0.0
ant CLI2.0.0

버전 외의 변경도 있습니다. SDK·CLI의 라이선스가 MIT에서 Apache 2.0으로 바뀌었습니다. API 키 전달 방식도 Authorization: Bearer 헤더로 바뀌었습니다. Admin API와 Enterprise Analytics API의 deprecated 필드 일부가 교체됐습니다. 예컨대 API 키의 workspace_id가 scope로 바뀝니다. 마이그레이션 가이드를 볼 때는 샘플링 파라미터만 보지 말고, 이 세 가지도 함께 확인해야 합니다.

마이그레이션 순서 — 400 케이스부터

순서는 단순합니다. SDK를 올리기 전에, 깨지는 호출부터 찾습니다. 버전 pin을 확인하고, 샘플링 파라미터를 제거하고, document 블록과 citations 형태를 고친 뒤, CI에서 400 케이스를 먼저 테스트합니다.

마이그레이션 순서: 버전 pin 확인 → 파라미터 제거 → document 이동 → citations 수정 → 400 테스트
흐름 — 버전 pin 확인 → 파라미터 제거 → document 이동 → citations 수정 → 400 테스트

아직 확인되지 않은 세 가지가 있습니다

보도 단계의 공개인 만큼, 섣불리 메우지 않고 미확인으로 남겨두는 편이 맞습니다.

버전 헤더 하나가 API 동작을 바꿉니다. 모델을 바꾸지 않아도, SDK를 올리는 순간 예전 요청이 400이 됩니다. 마이그레이션의 첫 단계는 새 기능을 쓰는 것이 아니라, 깨지는 호출을 찾는 것입니다.

실무 판단 — pin하고, 400부터 테스트하라

Claude API를 쓰는 모든 팀에게 직접적인 breaking change입니다. 에이전트·코딩 도구를 Claude API 위에 올린 팀은 릴리스 전 검증이 필수입니다. 확인할 순서는 이렇습니다. 먼저 CI에 SDK 버전을 pin하고, 다음으로 마이그레이션 가이드대로 400 케이스(샘플링 파라미터·document 위치·citations 형태)를 테스트하고, 그다음에 새 SDK 메이저 버전으로 올립니다. 순서를 바꾸면, 깨지는 호출이 프로덕션에서 먼저 발견됩니다.

원문 이슈

AX TrendAnthropicAI 코딩