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 상태가 요청 작업의 완료를 뜻하지는 않습니다. 거절된 작업을 계속 다시 보내지 말고 결과를 명시적으로 처리하세요.

Agent 루프와 분리해 실패 요청 하나를 재현하기

운영 연동을 바꾸기 전에 비밀 정보와 비공개 입력을 제거한 실패 요청을 저장합니다. endpoint 호스트, 모델 ID, SDK 버전, HTTP 상태, 오류의 type과 message, 제공된다면 request ID도 기록합니다. 원본 응답은 로컬에 보관합니다. “400 Bad Request”만 복사하면 thinking 호환 문제와 메시지 순서 오류를 구분할 단서가 사라집니다. 단독 진단 중에는 애플리케이션의 자동 재시도를 끕니다. 잘못된 요청은 같은 내용을 열 번 보내기보다 설정을 고쳐야 합니다.

앞의 최소 JSON을 request.json으로 저장하고 새 대화에서 시작합니다. 아래 명령은 Anthropic 기본 endpoint를 호출하므로 실행하면 API 사용량이 발생합니다. 승인된 계정과 환경에 설정된 ANTHROPIC_API_KEY가 전제입니다. 키를 명령에 직접 넣거나 저장한 응답을 공개하지 마세요. 이 코드는 진단 절차이며, 편집 과정에서 모델 호출에 성공했다는 기록이 아닙니다.

curl --silent --show-error \
  --dump-header response.headers \
  --output response.json \
  --write-out 'HTTP %{http_code}\n' \
  https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header 'anthropic-version: 2023-06-01' \
  --header 'content-type: application/json' \
  --data-binary @request.json

터미널에 표시된 HTTP 상태와 JSON 본문을 각각 확인합니다. curl 종료 코드 0은 전송이 끝났다는 뜻입니다. HTTP 오류 처리 옵션이 없다면 API가 요청을 수락했다는 의미는 아닙니다. 최소 요청이 성공하면 원래 system prompt, 도구, 기록을 한 묶음씩 추가합니다. 어느 추가 단계에서 실패했는지 알면 모델·SDK·도구를 동시에 바꾸는 것보다 원인을 좁히기 쉽습니다.

최소 요청도 400이면 실제 직렬화된 JSON을 예제와 비교합니다. 앱 설정에서 thinking.type: disabled, 수동 token budget, 강제 tool choice를 지워도 SDK 래퍼가 다시 넣을 수 있습니다. 설정 객체만 보지 말고 최종 요청 본문을 확인하세요. 게이트웨이를 쓴다면 해당 서비스의 기본 API 호환 문서를 확인하고, 모든 필드가 그대로 전달된다고 가정하지 않습니다.

요청과 응답 파서를 함께 수정하기

전후 비교는 JSON 유효성뿐 아니라 동작 변화까지 포함해야 합니다.

예를 들어 경비 앱은 텍스트에 “저장했습니다”라고 적혔다는 이유만으로 기록을 만들면 안 됩니다. 허용된 tool_use 이름을 확인하고 입력과 업무상 권한을 검증해야 합니다. 결과를 돌려줄 때 assistant content를 보존하고 해당 tool-use ID와 연결합니다. 여러 호출이 있다면 각각 연결해야 하며, 모든 결과를 마지막 호출에 붙여서는 안 됩니다.

auto에서는 도구를 호출하지 않는 응답도 처리해야 할 분기입니다. 사용자에게 미완료 상태를 알리거나 부족한 정보를 요청합니다. tool_choice: any로 재시도하면 비호환 문제가 다시 생깁니다. 지원 플랫폼의 strict: true도 입력 구조를 제한할 뿐, 금액·수취인·날짜의 정확성까지 보장하지 않습니다. schema 검사 뒤에도 업무 검증이 필요합니다.

새 대화와 기록 문제를 따로 진단하기

system 지시 A로 성공한 뒤 A를 B로 바꾸고 A 이후 생성된 서명된 thinking을 재전송한다고 가정해 봅시다. 문서의 binding 규칙에서는 해당 thinking이 변경된 대화 앞부분과 맞지 않습니다. max_tokens를 늘려도 이 관계는 복구되지 않습니다. 이전 block 없이 새 대화로 같은 작업을 재현합니다. 새 대화가 성공하면 token 예산보다 기록 변경을 조사해야 합니다.

원래 대화는 변경하지 않는 기록으로 보관합니다. 대체 서명을 만들거나 다른 계정의 thinking을 복사하지 마세요. 의도적인 기록 수정은 영향받는 block과 지원 제어에 대한 공식 절차로 처리합니다. 임시 진단용 새 대화를 모든 사용자의 문맥을 몰래 지우는 운영 정책으로 바꾸지 않습니다. 순수한 추가형 대화와 앱이 실제로 수행하는 기록 수정을 각각 시험합니다.

모델 전환도 별도 시험입니다. 읽을 수 없는 block은 제거된 뒤 200이 반환될 수 있지만 binding 위반은 요청을 실패시킬 수 있습니다. 로그에서 “요청 실패”와 “기록 처리 변경을 동반한 성공”을 구분하세요. 재개 작업과 새 작업은 화면의 사용자 메시지가 같아도 문맥이 같지 않을 수 있습니다.

운영 전환 전 응답 승인 조건 정하기

최소 텍스트 예제의 승인 조건은 HTTP 성공, 사용 가능한 텍스트, 적절한 종료 이유, 입력에 맞는 요약입니다. 도구 흐름에는 이름·schema·결과 연결·최종 업무 완료가 추가됩니다. max_tokens 종료는 한도 도달입니다. 반쯤 작성된 JSON이나 설명을 완성으로 처리하지 마세요. 거절 역시 별도 결과이며 일시적인 네트워크 장애용 자동 재시도에 넣지 않습니다.

작은 회귀 사례 여섯 개를 유지합니다. 새 텍스트 요청, 유효한 도구 작업, 도구 없는 응답, 추가만 한 두 번째 턴, 의도적으로 바꾼 기록 앞부분, 여러 block 유형을 포함한 파서 fixture입니다. 마지막 사례는 합성 JSON으로 로컬 실행할 수 있지만 검증 대상은 앱 파서이지 Sonnet 행동이 아닙니다. 로컬 검사를 먼저 하고 승인된 입력으로 제한된 온라인 샘플을 실행해 구·신 앱 결과를 비교합니다.

HTTP 오류율이 낮아져도 잘못된 업무 동작이나 필수 문맥 손실이 있으면 롤백합니다. 승인 전까지 기존 요청 어댑터와 새 어댑터를 구분해 보존하세요. 요청과 업무 결과가 모두 계약을 충족해야 마이그레이션이 끝납니다. 200 응답만으로는 부족합니다.

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

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