Anthropic이 2026년 10월 21일 Claude API 버전 2026-10-21과 새 SDK를 공개했어요. 기존 요청에 문서 블록이나 인용 정보를 넣거나 temperature 값을 보내던 앱은 그대로 버전을 올리면 400 오류가 날 수 있습니다. SDK를 업데이트하기 전에 요청을 만드는 코드와 배치 요청까지 같이 살펴보세요.
헤더만 바꾸면 끝나는 업데이트가 아니에요
새 API 버전은 요청의 의미를 바꾸는 변경도 포함합니다. SDK를 쓰면 SDK의 주요 버전에 따라 기본 anthropic-version 헤더가 정해져요. 새 SDK를 설치하는 순간 호출 버전도 바뀔 수 있으니, SDK 설치 변경을 단순 의존성 업데이트로만 취급하면 놓치는 부분이 생깁니다.
Anthropic은 새 API 버전으로 옮기기 전에 적용되는 변경을 확인하고, 실제 통합 코드를 수정한 뒤 배포 전에 해당 버전으로 시험하라고 안내합니다. API를 직접 호출한다면 요청 헤더도 확인해야 합니다.
400 오류를 만들 수 있는 요청 세 가지
첫째, assistant 메시지에 document 블록을 바로 넣는 요청이에요. 2026-10-21 버전에서는 이 요청이 400 오류를 돌려줍니다. 문서는 user 메시지에 보내야 합니다. 다만 웹 fetch 도구 결과 안에 중첩된 문서 블록은 허용된다고 안내돼 있어요.
둘째, user 메시지의 text 블록에 비어 있지 않은 citations 배열을 넣는 경우예요. search_result 안의 text 블록도 여기에 포함됩니다. user 쪽 text 블록에서 citations를 제거해야 합니다. 이전 assistant 답변을 다시 보내는 경우처럼 assistant 메시지의 인용 정보는 이 변경으로 금지되지 않습니다.
셋째, Messages API, 토큰 수 계산, 메시지 배치 요청에 temperature, top_p, top_k를 보내는 경우입니다. 새 버전은 기본값을 넣었더라도 이 필드를 받지 않아요. 필드를 삭제하고 모델이 제공하는 기본 샘플링 동작을 써야 합니다. 예전처럼 낮은 temperature를 지정할 대체 필드는 문서에 없습니다.
SDK를 쓰면 타입과 기본값도 확인하세요
Anthropic은 새 API 버전을 사용하는 SDK 주요 버전도 안내했어요. Python SDK는 2.0.0, TypeScript SDK는 1.0.0 등 언어별로 버전이 다릅니다. 사용하는 언어의 해당 버전과 변경 목록을 기준으로 확인하세요.
SDK의 MessageParam 타입도 달라졌습니다. 이전에는 한 타입을 여러 역할에 썼지만, 새 버전은 user, assistant, system 역할별 타입의 합집합입니다. 타입 이름을 생성자처럼 호출해 메시지를 만들던 코드는 TypeError가 나거나 타입 검사에서 지적될 수 있어요. 문서 예시처럼 역할이 정해진 객체를 만들어 타입을 붙이는 방식으로 고쳐야 합니다.
배포 전에 검색할 위치
저장소에서 먼저 요청 빌더와 공통 래퍼를 검색하고 세 필드가 남아 있는지 확인하세요. 메시지를 직접 만드는 경로뿐 아니라 토큰 계산, 배치 요청, 테스트 fixture도 살펴봐야 합니다. 외부 API 게이트웨이가 헤더를 덮어쓰는 구조라면 실제 전송값도 확인합니다.
Amazon Bedrock을 통해 호출한다면 한 가지 더 봐야 해요. 2026-10-21 버전은 Claude 4.7 이상에서만 사용할 수 있다고 안내되어 있습니다. 이전 모델을 계속 부르는 연동은 현재 SDK와 헤더를 그대로 유지하거나, 모델을 먼저 바꾼 뒤 버전을 올려야 합니다.
한 번에 모든 호출을 바꾸기보다 요청 종류를 나눠 점검하면 영향 범위를 찾기 쉽습니다. 새 버전에서 삭제된 필드를 보내지 않는지, user와 assistant 메시지의 블록 위치가 맞는지, 사용하는 배포 환경이 해당 버전을 지원하는지 확인한 뒤 실제 API 버전으로 통합 테스트를 통과시키세요.
참고한 자료
- Claude Platform release notes https://platform.claude.com/docs/en/release-notes/overview (확인일 2026-10-28)
- Migrating to API version 2026-10-21 https://platform.claude.com/docs/en/api/migration-2026-10-21 (확인일 2026-10-28)