Sonnet 5.5 업데이트 후 API 400 오류 해결하기

모델 ID만 바꾸면 정상 작동하던 Sonnet 5 연동이 깨질 수 있습니다. Sonnet 5.5는 허용 thinking 설정, 강제 도구 사용, thinking 이력 처리, 일부 도구 호환성을 변경했습니다. 업데이트 뒤 HTTP 400이 발생하면 인증을 바꾸거나 같은 요청을 재시도하기 전에 오류 본문과 실제 전송 내용을 살펴보세요.

이 글은 2026년 9월 29일 확인한 Anthropic의 Sonnet 5.5 마이그레이션 가이드와 변경 문서를 따릅니다. 예제는 문서에 기반한 요청 형태이며 Ofox가 실제 API에서 모든 오류를 재현했다는 뜻이 아닙니다. 401, 429, 공급사별 404는 다른 조사가 필요합니다.

호환되지 않는 필드 찾기

computer use 행을 모든 공급사에 적용하지 마세요. 같은 공식 페이지에 Amazon Bedrock은 이전 computer_20251124 도구를 허용한다고 명시돼 있습니다. 플랫폼 범위도 해결 조건의 일부입니다.

disabled thinking을 신중하게 대체하기

도구 없는 최소 텍스트 요청의 경우 네이티브 Claude API POST /v1/messages 본문을 문서에 따라 다음처럼 작성할 수 있습니다.

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "high"},
  "messages": [{"role": "user", "content": "Return a one-sentence summary of this task: verify a CSV total."}]
}

본문만으로 완전한 HTTP 클라이언트가 되지는 않습니다. Messages API가 요구하는 인증 및 API 버전 헤더를 추가해야 합니다. 자격 증명은 자신의 환경에 두고 복사하는 예제나 로그에는 넣지 마세요.

between_tools는 시작 시점의 thinking을 끄지만 모든 도구 흐름에서 thinking 블록이 사라진다는 보장은 아닙니다. 도구 사이 진행 메모에도 해당 블록 유형을 쓸 수 있습니다. low, medium, high만 허용하며 xhigh와 max는 지원하지 않습니다. display, budget_tokens 같은 추가 필드도 허용하지 않습니다. xhigh 또는 max에는 adaptive thinking을 쓰세요. 호환되지 않는 설정 조합의 검증 오류는 재시도로 해결되지 않습니다.

강제 호출을 바꿔도 검증은 유지하기

tool_choice를 auto로 바꾸면 모델이 도구 호출 여부를 선택합니다. 지원 도구 정의에 strict: true를 넣으면 입력 형태를 검증하지만, 그 도구를 선택하도록 강제하지는 않습니다. 기대한 호출이 실제로 일어났는지 애플리케이션이 확인해야 합니다. 스키마 기능도 플랫폼에 따라 다릅니다. 마이그레이션 문서는 Amazon Bedrock의 Sonnet 5.5에서 strict tool use를 포함한 구조화 출력을 사용할 수 없다고 설명합니다.

추출 서비스라면 도구 호출 자체가 필요한지 검토하세요. 결과가 행동이 아닌 데이터라면 구조화 출력이 적합할 수 있습니다. 올바른 출력뿐 아니라 필수 데이터 누락, 거부, 예상 밖 자연어 응답도 테스트합니다. 400이 사라졌다는 이유만으로 마이그레이션 완료를 선언하지 마세요.

대화 이력 보존하기

Sonnet 5.5의 thinking 블록은 모델과 대화에 바인딩됩니다. 이전 시스템 프롬프트, 도구 정의, 메시지를 수정한 뒤 후속 블록을 재전송하면 바인딩 오류가 발생할 수 있습니다. 공식 기본 강제 적용은 지정 플랫폼에서 2026년 8월 31일 00:00 UTC 이후 생성한 계정에 해당합니다. 이전 계정과 명시적 참여 설정은 따로 확인해야 합니다.

가장 단순한 설계는 이력을 추가만 하는 방식입니다. 반환된 블록을 수정하지 말고 대화 중 변경에는 문서에 설명된 기능을 사용하세요. 의도적으로 이력을 수정한다면 영향을 받는 블록과 beta 제어 처리법을 따릅니다. 모든 요청에서 모든 thinking 블록을 지우는 것을 만능 해결책으로 쓰면 대화가 달라지고 유용한 문맥을 잃을 수 있습니다.

모델 전환에는 별도 규칙이 있습니다. 대상 모델이 읽지 못하는 블록을 제거하는 것과, 수정된 접두부 때문에 발생하는 바인딩 오류는 다릅니다. 모든 문제를 “invalid signature”로 묶지 말고 실제 오류나 변환 메타데이터를 기록하세요. 이전 사례는 thinking 서명 오류 해결 가이드를 참고할 수 있습니다.

성공 응답도 점검하기

일부 회귀는 HTTP 오류를 반환하지 않습니다. 도구 사이의 긴 진행 메모가 thinking 블록으로 들어오고 adaptive의 기본 표시 동작에 따라 텍스트가 생략될 수 있습니다. text 블록만 표시하는 UI는 요청이 유효해도 아무 반응이 없는 것처럼 보일 수 있습니다. adaptive thinking의 thinking.display나 지원되는 between_tools 모드의 표시 동작을 확인하세요.

거부와 전송 실패도 구분해야 합니다. 문서는 HTTP 200과 stop_reason: refusal, 추가 세부 정보를 반환하는 경우를 설명합니다. 성공 HTTP 상태가 요청 작업의 완료를 뜻하지는 않습니다. 거절된 작업을 계속 다시 보내지 말고 결과를 명시적으로 처리하세요.

운영 트래픽을 전환하기 전에 검증하기

일반 텍스트, 도구 호출, 여러 턴 대화, 수정된 이력, 스트리밍 업데이트, 거부 처리 경로를 포함한 작은 테스트 세트를 유지하세요. 요청 스키마, 응답 파서, 도구 결과 연결, 사용자에게 보이는 출력을 확인합니다. 결과마다 클라이언트 버전과 정확한 모델 ID를 저장하고, 실패를 조사하는 동안 기존 연동으로 돌아갈 설정을 남겨 두세요.

전체 배포 체크리스트는 업그레이드 판단 가이드, CLI 선택은 Claude Code 설정 가이드를 참고하세요. 이 글은 네이티브 API 변경을 다룹니다. 타사 게이트웨이는 자체 변환 계층과 오류를 추가할 수 있습니다.