클로드 하이쿠 5.5 API 400 에러 원인과 수정 방법 정리

클로드 하이쿠 5.5 API는 하이쿠 4.5용으로 짠 요청 중 budget_tokens, temperature·top_p·top_k, 어시스턴트 프리필을 넣으면 400 에러를 돌려준다. 앤트로픽은 릴리스 노트에서 하이쿠 5.5(claude-haiku-5-5)를 2026년 10월 7일 출시했다고 밝혔고, 모델 ID만 바꿔서는 기존 코드가 그대로 돌지 않는다. 아래에서 400이 나는 항목과 고치는 방법, 토큰·요금이 달라지는 점을 정리한다(기준일 2026년 10월 10일).

클로드 하이쿠 5.5 API에서 400 에러가 나는 요청

앤트로픽 마이그레이션 가이드에 따르면 아래 요청은 하이쿠 5.5에서 거절된다.

요청에 넣은 값	하이쿠 5.5 결과	고치는 방법
thinking: {"type": "enabled", "budget_tokens": N}	400	thinking을 {"type": "adaptive"}로 바꾸고 output_config.effort로 사고량 조절
temperature	1이 아니면 400	요청에서 삭제
top_p	0.99(기본값)가 아니면 400, 1도 400	요청에서 삭제
top_k	어떤 값이든 400	요청에서 삭제
temperature와 top_p 동시 사용	400	둘 다 삭제
messages가 어시스턴트 턴으로 끝나는 프리필	사고를 꺼도 400	사용자 턴으로 끝내고 용도별로 대체
computer_20250124 도구	400	Claude API·구글 클라우드는 computer_toolset_20260801, 아마존 베드록은 computer_20251124(컴퓨터 사용 이전 안내)
system·tools·이전 메시지를 바꾼 뒤 사고 블록을 다시 보냄	400	대화를 이어 붙이기만 하는 방식으로 유지(해당 안내)

사고 블록 항목은 2026년 8월 31일 0시(UTC) 이전에 만든 계정이라면 thinking.block_binding.prefix_mismatch_behavior를 설정한 요청에서만 에러가 난다.

temperature·top_p·top_k 삭제 방법

마이그레이션 가이드는 하이쿠 5.5에서 세 파라미터를 모두 빼고 프롬프트로 응답 성향을 조절하라고 안내한다. temperature를 쓴다면 값이 1이어야 하고, top_p는 기본값 0.99여야 한다. temperature: 0처럼 1이 아닌 값을 넣던 코드는 값을 바꾸지 말고 해당 줄을 지워야 한다.

budget_tokens를 adaptive thinking으로 바꾸기

하이쿠 4.5에서 사고 예산을 직접 지정하던 요청은 아래처럼 바꾼다.

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

적응형 사고는 기본으로 켜져 있어서 thinking을 설정하지 않아도 응답이 thinking 블록으로 시작할 수 있다. 사고를 아끼려고 예산을 작게 줬던 코드는 effort를 낮추면 된다. 낮은 단계에서는 간단한 요청에서 사고를 건너뛰기도 한다.

이때 바뀌는 동작이 세 가지 있다.

• 첫 번째 콘텐츠 블록을 답으로 읽는 코드는 type이 text인 블록을 골라 읽도록 고쳐야 한다.
• 사고 토큰도 max_tokens에 포함되므로 값이 작으면 사고 직후 stop_reason: "max_tokens"로 끊겨 본문이 비어 올 수 있다.
• 사고 블록의 thinking 필드는 기본으로 비어 있고 서명만 온다. 요약 텍스트가 필요하면 "display": "summarized"를 넣는다.

어시스턴트 프리필 대체하기

프리필은 messages 마지막에 어시스턴트 턴을 두고 모델이 이어 쓰게 하는 방식이다. 하이쿠 4.5는 사고를 끈 상태에서 받아 줬지만 5.5는 400을 돌려준다. 용도에 따라 이렇게 바꾼다.

프리필을 쓰던 목적	대체 방법
출력 형식 고정(JSON 등)	구조화된 출력, 분류는 enum 필드가 있는 도구
서두 문장 제거	시스템 프롬프트에 바로 답하라고 지시
끊긴 응답 이어 쓰기	사용자 메시지에 "이전 응답이 ...로 끝나고 중단됐다. 이어서 써라"를 넣기
맥락 상기	사용자 턴에 넣기

아마존 베드록에서는 하이쿠 5.5의 구조화된 출력을 쓸 수 없다. 그 경우 형식을 프롬프트로 설명하거나 strict가 없는 도구를 쓰고, 코드에서 결과를 검증한다.

토큰 수와 요금이 달라지는 점

하이쿠 5.5는 4.7 이후 모델과 같은 새 토크나이저를 쓴다. 같은 글이 하이쿠 4.5보다 약 30% 많은 토큰으로 계산되므로 max_tokens와 비용 추정을 새 모델로 다시 세어야 한다. 이미지는 긴 변 2,576픽셀까지 줄이지 않는 고해상도 구간을 쓰기 때문에, 2,000×1,500 픽셀 이미지는 시각 토큰이 약 2.5배 든다. 이전 턴의 사고 블록도 입력 토큰으로 남는다.

단가는 앤트로픽 요금 페이지 기준으로 하이쿠 5.5가 입력 100만 토큰당 0.10달러, 출력 0.50달러다. 프롬프트가 10만 토큰을 넘는 요청은 입력 0.50달러, 출력 2.50달러로 올라간다. 하이쿠 4.5는 입력 1달러, 출력 5달러다.

단가는 낮아졌지만 토큰 수가 30% 늘고 긴 프롬프트 구간 가격이 따로 있어서, 실제 청구액은 새 모델로 센 토큰으로 다시 계산해야 한다. 우선순위 티어(Priority Tier)를 하이쿠 4.5에 계약해 둔 조직은 하이쿠 5.5에서 지원되지 않으므로 용량을 따로 계획해야 한다.

수정 후 정상 동작 확인하는 방법

모델 ID를 claude-haiku-5-5로 바꾼 뒤 실제 요청 한 건을 보내 HTTP 200이 오는지 본다. 응답의 content에서 type이 text인 블록에 답이 있는지, stop_reason이 max_tokens가 아닌지 본다. stop_reason이 refusal이면 하이쿠 5.5의 안전 분류기가 요청을 거절한 것이고, 서버 쪽 대체 모델은 없으므로 코드에서 처리해야 한다. 코드가 많다면 클로드 코드에서 /claude-api migrate this project to claude-haiku-5-5를 실행해 모델 ID 교체와 파라미터 수정을 한 번에 시킬 수 있다.

자주 묻는 질문

하이쿠 5.5에서 temperature를 1로 넣으면 에러가 나나?

나지 않는다. 1은 허용되는 값이고 그 외 값이 400이다. 다만 공식 안내는 세 파라미터를 모두 생략하라는 것이다.

하이쿠 4.5는 언제까지 쓸 수 있나?

종료 일정은 앤트로픽의 모델 지원 종료 페이지에서 확인한다.

매니지드 에이전트를 쓰면 코드를 고쳐야 하나?

Claude Managed Agents를 쓰면 모델 이름만 바꾸면 된다. 위 변경은 Messages API를 직접 호출하는 코드에 해당한다.