사고 문제 해결

이 페이지는 사고(thinking)를 구성하거나 thinking 블록을 왕복(round-tripping, 반환된 thinking 블록을 이후 요청에서 다시 전송하는 것)할 때 가장 흔히 발생하는 실패를 다룹니다. 첫 번째 섹션은 각 모델을 지원되는 사고 구성 및 거부되는 구성에 매핑하며, 그 이후의 섹션들은 각각 관찰되는 증상에서 시작하므로 오류 메시지나 예상치 못한 응답을 원인 및 해결 방법에 직접 대응시킬 수 있습니다. 사고가 어떻게 작동하는지 알아보려면 사고 개요를 참조하세요.

모델별 사고 지원, 기본값 및 거부되는 구성

대부분의 사고 구성 오류는 요청의 thinking.type 값과 모델이 지원하는 값이 일치하지 않아 발생합니다. 대부분의 모델에서 사고는 thinking: {type: "adaptive"}로 실행되며, 많은 모델에서 기본적으로 켜져 있습니다. 일부 이전 모델은 대신 thinking: {type: "enabled", budget_tokens: N}으로 구성하는 레거시 수동 모드인 extended thinking(확장 사고)을 사용합니다.

"Extended thinking"(확장 사고)(thinking.type: "enabled"와 budget_tokens 사용)는 Claude 4.6 모델에서 지원 중단되었습니다(이를 사용하는 요청은 여전히 성공합니다). Claude 4.7 및 이후 모델은 이를 지원하지 않으며, 이를 사용하는 요청을 거부하고 400 오류를 반환합니다. 사고를 지원하는 Claude 4.5 및 이전 모델에서는 확장 사고가 사용 가능한 유일한 사고 모드입니다. Claude Mythos Preview는 두 모드를 모두 지원합니다. 두 모드를 모두 사용할 수 있는 경우에는 대신 adaptive thinking(적응형 사고)을 사용하세요.

아래 표는 각 모델이 지원하는 항목, 기본값, 그리고 400 오류로 거부하는 thinking.type 값을 나열합니다. 거부 항목에 나열되지 않은 값은 모두 허용됩니다. "between_tools"는 Claude Sonnet 5.5만 허용하며, 이 모델에서는 "disabled" 대신 이 값을 사용합니다.

¹ 이 모델들에서 enabled와 budget_tokens는 여전히 작동하지만 지원 중단되었습니다. 대신 적응형 사고를 사용하세요.
² Claude Opus 5와 Claude Haiku 5.5는 effort high 이하에서 "disabled"를 허용합니다. effort xhigh 또는 max와 함께 사용하면 400 오류가 반환됩니다. Claude Opus 5에서는 이 제한이 각 요청마다 적용됩니다. Claude Haiku 5.5에서는 현재 적용 중인 수준과 다른 메시지별 effort도 400 오류를 반환합니다.
³ Claude Sonnet 5.5는 effort high 이하에서 "between_tools"를 허용합니다. effort xhigh 또는 max와 함께 사용하면 400 오류가 반환되며, 현재 적용 중인 수준과 다른 메시지별 effort도 마찬가지입니다.

항상 켜짐으로 표시된 모델은 사고를 끌 수 없습니다. 켜짐으로 표시된 모델은 기본적으로 사고를 사용합니다. Claude Opus 5, Claude Sonnet 5, Claude Haiku 5.5는 thinking: {type: "disabled"}를 허용합니다. Claude Sonnet 5.5에서 사전 사고를 끄려면 thinking: {type: "between_tools"}를 보내세요.

이전 Claude 4 모델(Claude Opus 4.1, Claude Sonnet 4, Claude Opus 4)은 확장 사고만 지원합니다. 이 모델들의 가용성은 모델 지원 중단을 참조하세요. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5는 Anthropic의 명시적인 승인이 없는 한 zero data retention(제로 데이터 보존) 환경에서 사용할 수 없습니다.

400 오류에서 "thinking.type.enabled"가 지원되지 않는다고 표시됨

요청이 다음과 같은 메시지의 400 오류로 실패합니다:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

이는 요청한 모델에서 확장 사고가 제거되었기 때문에 발생합니다(모델별 구성 표 참조).

요청을 thinking: {type: "adaptive"}로 전환하고 budget_tokens 대신 effort로 사고 깊이를 조정하세요. 적응형 사고로 마이그레이션에서 변환 과정을 안내합니다.

thinking: {type: "disabled"}를 보낸 후 400 오류가 발생하는 경우

요청이 400 오류로 실패합니다. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Opus 5.5, Claude Mythos 5에서는 메시지가 다음과 같습니다:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

이 모델들 중 확장 사고를 허용하는 유일한 모델인 Claude Mythos Preview에서는 메시지가 다음과 같습니다:

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

이는 이 모든 모델에서 사고가 항상 켜져 있기 때문에 발생합니다(모델별 구성 표 참조).

thinking 매개변수를 생략하세요. 이 모델들은 별도의 구성 없이 사고합니다. 응답에서 사고 텍스트를 제외하는 것이 목적이었다면, 사고를 비활성화하는 대신 display: "omitted"를 사용하세요. 사고 표시 제어를 참조하세요.

Claude Opus 5와 Claude Haiku 5.5는 effort high 이하에서만 thinking: {type: "disabled"}를 허용하므로, 해당 모델에서도 "disabled"에 대한 400 오류가 발생할 수 있습니다. effort xhigh 또는 max와 함께 사용하면 거부됩니다. effort 수준을 낮추거나, thinking을 {"type": "adaptive"}로 설정하세요.

Claude Sonnet 5.5에서는 thinking: {type: "disabled"}가 모든 effort 수준에서 400 오류를 반환합니다. 메시지는 다음과 같습니다:

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

Claude Sonnet 5.5에서 사전 사고를 끄려면 대신 effort high 이하에서 thinking: {type: "between_tools"}를 보내세요.

400 오류에서 "thinking.type.between_tools"가 지원되지 않는다고 표시되는 경우

요청이 다음 메시지와 함께 400 오류로 실패합니다:

"thinking.type.between_tools" is not supported for this model.

이는 thinking: {type: "between_tools"}를 Claude Sonnet 5.5만 허용하기 때문에 발생합니다(모델별 구성 표 참조).

between_tools는 Claude Sonnet 5.5에만 보내세요. 다른 모델에서는 thinking을 생략하거나, 표에서 거부 항목으로 나열되지 않은 thinking.type 값을 사용하세요.

400 오류에서 사고가 비활성화된 경우 해당 effort 수준이 지원되지 않는다고 표시되는 경우

Claude Sonnet 5.5에서 effort xhigh 또는 max로 thinking: {type: "between_tools"}를 사용한 요청이 다음 메시지와 함께 400 오류로 실패합니다:

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

이는 Claude Sonnet 5.5가 effort high 이하에서만 between_tools를 허용하기 때문에 발생합니다. 요청에서 "disabled"를 보내지 않았더라도 between_tools에는 사전 사고가 없으므로 메시지에는 사고가 비활성화되었다고 표시됩니다. 메시지에는 요청에서 보낸 수준이 명시됩니다.

effort를 high 이하로 낮추세요. xhigh 또는 max로 실행하려면 적응형 사고를 사용하세요. 즉, thinking 필드를 생략하거나 thinking: {"type": "adaptive"}를 보내세요. 메시지의 "enable thinking"은 이를 의미합니다. Claude Sonnet 5.5는 "enabled"를 400 오류로 거부합니다.

Claude Haiku 5.5는 요청이 effort xhigh 또는 max로 thinking: {type: "disabled"}를 보낼 때 동일한 메시지를 반환합니다. 이 모델은 high 이하에서만 "disabled"를 허용합니다. effort를 낮추거나, thinking을 {"type": "adaptive"}로 설정하세요.

400 오류에서 사고가 비활성화된 경우 effort를 변경할 수 없다고 표시되는 경우

Claude Sonnet 5.5에서 thinking: {type: "between_tools"}를 사용하면서 메시지별 effort로 수준을 변경한 요청이 다음 메시지와 함께 400 오류로 실패합니다:

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

between_tools에는 사전 사고가 없으므로 메시지에는 사고가 비활성화되었다고 표시됩니다. between_tools를 사용하면 대화 도중에 effort를 변경할 수 없습니다. 현재 적용 중인 수준과 다른 메시지별 output_config.effort는 400 오류를 반환합니다. messages.N은 새 수준을 설정한 메시지의 위치입니다.

해당 메시지별 effort를 제거하거나 현재 적용 중인 수준으로 설정하세요. 턴마다 effort를 다르게 하려면 적응형 사고를 사용하세요. 즉, thinking 필드를 생략하거나 thinking: {"type": "adaptive"}를 보내세요. 메시지의 "enable thinking"은 이를 의미합니다.

Claude Haiku 5.5는 thinking: {type: "disabled"}를 사용한 요청이 현재 적용 중인 수준과 다른 메시지별 effort를 설정할 때 동일한 메시지를 반환합니다. 해당 메시지별 effort를 제거하거나, 턴마다 effort를 다르게 하려면 thinking을 {"type": "adaptive"}로 설정하세요.

400 오류에서 적응형 사고가 지원되지 않는다고 표시됨

요청이 다음과 같은 메시지의 400 오류로 실패합니다:

adaptive thinking is not supported on this model

이는 모델이 확장 사고만 지원하기 때문에 발생합니다(모델별 구성 표 참조).

대신 thinking: {type: "enabled", budget_tokens: N}을 사용하세요. 구성 방법은 확장 사고를 참조하세요.

400 오류에서 thinking 블록을 수정할 수 없다고 표시됨

도구 결과를 반환하는 요청이 다음 내용을 포함하는 메시지의 400 invalid_request_error로 실패합니다:

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified

멀티턴 및 도구 사용 대화에서는 thinking 및 redacted_thinking 블록을 포함한 이전 어시스턴트 메시지를 API로 다시 전송하며, API는 이들이 수정되지 않은 채로 도착했는지 검증합니다. 이 오류는 다시 전송한 어시스턴트 메시지가 API가 반환한 것과 다를 때 발생하며, 대부분 코드가 콘텐츠 블록을 유형별로 필터링하면서 redacted_thinking 블록을 누락하거나, 어시스턴트 메시지를 그대로 되돌려 보내는 대신 재구성하기 때문입니다.

thinking 블록을 포함하여 어시스턴트 턴을 그대로 되돌려 보내세요. 규칙은 thinking 블록 보존을 참조하고, 모든 SDK에서의 올바른 코드는 도구 및 멀티턴 워크플로에서의 사고의 왕복 예제를 참조하세요.

400 오류에서 thinking 블록 서명이 유효하지 않다고 표시됨

이전 thinking 블록을 재전송하는 Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 또는 Claude Haiku 5.5에 대한 요청이 다음 메시지와 함께 400 invalid_request_error로 실패합니다:

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

요청에서 thinking-binding-controls-2026-08-01 베타 헤더를 보내지 않은 경우, 메시지에 That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.가 추가됩니다.

메시지는 보통 무엇이 변경되었는지를 명시하는 문장으로 끝납니다. system 프롬프트, tools 목록, 처음으로 달라진 메시지나 블록, 누락되었거나 새로 추가된 콘텐츠, 또는 누락되었거나 순서가 바뀐 이전 thinking 블록 등입니다. 이 문장은 사람과 로그를 위한 것입니다. 문구가 변경될 수 있으므로 코드에서 이 문장을 기준으로 매칭하지 마세요.

메시지가 Invalid `signature` in `thinking` block에서 끝나는 경우, 서명 자체가 검증되지 않은 것입니다. 서명이 잘렸거나, 변경되었거나, 비어 있는 상태로 다시 전송된 것이며, 이 경우 prefix_mismatch_behavior는 적용되지 않습니다. 사고 텍스트를 편집한 경우에는 다른 오류가 반환됩니다. 400 오류에서 thinking 블록을 수정할 수 없다고 표시됨를 참조하세요.

Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5에서는 재전송된 thinking 블록보다 앞선 system 프롬프트, tools, 메시지가 변경되지 않은 경우에만 API가 해당 블록을 허용합니다. 접두사를 변경하지 않고 유지하기를 참조하세요. 이 오류는 요청 사이에 대화의 앞부분에서 무언가가 변경되었음을 의미합니다. 예를 들어 편집되거나, 순서가 바뀌거나, 제거된 턴, 삽입되었다가 나중에 제거된 턴별 리마인더, 재구성된 system 프롬프트나 tools 배열, 또는 최근 턴과 그 사고를 그대로 유지한 클라이언트 측 압축 등이 있습니다. 이 검사는 2026년 8월 31일 이후에 생성된 신규 계정과 thinking.block_binding.prefix_mismatch_behavior를 설정한 모든 요청에 적용됩니다. 서버 측 compaction(압축)과 context editing(컨텍스트 편집)은 이 검사를 트리거하지 않습니다.

이를 해결하려면 기록을 추가 전용(append-only)으로 유지하세요. 이전 턴은 보내고 받은 그대로 다시 전달하고, system이나 tools를 편집하는 대신 대화 중간 시스템 메시지로 지침을 추가하며, 잘라내기는 서버 측 컨텍스트 편집 또는 압축에 맡기세요. 동일한 요청 본문으로 재시도해도 오류는 해결되지 않습니다. 무효화된 추론 없이 이 요청을 계속하려면 thinking-binding-controls-2026-08-01 베타 헤더를 보내고 thinking.block_binding.prefix_mismatch_behavior를 "drop_block"으로 설정하세요. 또는 기록에서 모든 thinking 및 redacted_thinking 블록을 제거하고(최소한 명시된 블록과 그 이후의 모든 블록을, 해당 턴과 이후의 모든 턴에서), 각 턴의 다른 블록은 그대로 둔 채 한 번 재시도하세요. Claude Sonnet 5.5와 Claude Haiku 5.5에서 block_binding은 thinking: {"type": "adaptive"}에서만 작동합니다. Claude Sonnet 5.5에서 between_tools를 사용하거나 Claude Haiku 5.5에서 thinking: {"type": "disabled"}를 사용하는 경우, 기록을 추가 전용으로 유지하거나 편집된 턴부터 thinking 블록을 제거하세요.

대상 모델이 읽을 수 없는 모델의 블록은 이 오류를 발생시키지 않습니다. API는 해당 블록을 삭제하며, 베타 헤더를 사용하는 경우 input_transformations에 이를 보고합니다.

응답에서 thinking 필드가 비어 있음

응답에 thinking 블록이 포함되어 있지만 thinking 필드는 빈 문자열이고 signature 필드만 채워져 있습니다.

이는 최신 모델에서 display의 기본값이 "omitted"이기 때문에 발생하며, 이 경우 텍스트 없이 thinking 블록이 반환됩니다.

요약된 사고 텍스트를 받으려면 사고 구성에서 display: "summarized"를 설정하세요. 모델별 기본값은 사고 표시 제어를 참조하세요. 추론이 아니라 일부 모델이 도구 호출 사이에 작성하는 짧은 상태 줄만 원한다면 대신 display: "updates"(베타)를 설정하세요. 도구 호출 사이의 진행 업데이트를 참조하세요.

thinking 필드가 비어 있어도 블록은 완전합니다. 추론 내용은 signature에 담겨 있습니다. 다른 블록과 마찬가지로 턴과 함께 다시 보내세요. 어시스턴트 턴을 반환된 그대로 다시 보내기를 참조하세요.

일부 턴에서 thinking 블록이 나타나지 않음

사고가 구성되어 있는데도 일부 응답에 thinking 블록이 전혀 포함되지 않습니다.

이는 적응형 모드에서 정상입니다. Claude는 직접 답변할 수 있을 만큼 간단하다고 판단한 요청에서는 사고를 건너뜁니다.

사고를 더 자주 또는 더 깊게 수행하기를 원한다면 effort를 높이거나 프롬프팅으로 조정하세요. Claude의 사고 빈도 조정을 참조하세요.

강제 tool_choice({"type": "any"} 또는 이름이 지정된 도구)도 thinking 블록을 반환하지 않습니다. 응답이 도구 호출로 시작됩니다. 모델이 도구를 호출하기 전에 사고하도록 하려면 tool_choice: {"type": "auto"}를 사용하고 프롬프트에서 도구를 언제 사용할지 지정하세요.

텍스트 출력에 도구 호출이나 XML 태그가 나타남

응답이 간혹 tool_use 블록을 내보내는 대신 도구 호출을 텍스트에 작성하거나, 보이는 텍스트에 <thinking> 또는 기타 내부 XML 태그를 포함합니다. 유출된 도구 호출은 절대 실행되지 않으며, 에이전트 루프에서는 유출된 텍스트가 대화 기록에 남아 이후 턴에도 영향을 미칩니다.

이는 Claude Opus 5에서 사고가 비활성화되었을 때 발생하며, 검색과 같이 도구 사용이 많은 워크로드에서 가장 흔합니다. 모델에게 사고하지 말거나 추론하지 말라고 지시하는 시스템 프롬프트 규칙은 태그 유출을 증가시킵니다.

사고를 다시 활성화하고(기본값) 대신 낮은 effort 수준으로 토큰 비용을 제어하세요. 통합에서 사고를 반드시 비활성화 상태로 유지해야 한다면 사고 비활성화 상태로 실행의 프롬프팅 완화 방법을 적용하세요.

응답이 stop_reason: "max_tokens"로 중단됨

응답이 stop_reason: "max_tokens"로 끝나며, 종종 텍스트 블록이 잘리거나 누락됩니다.

이는 사고 토큰이 max_tokens에 포함되어 계산되기 때문에 발생하며, 긴 사고 과정이 텍스트 응답이 완료되기 전에 예산을 소진할 수 있습니다.

사고와 텍스트 모두를 위한 여유를 두도록 max_tokens를 높이거나, Claude가 사고에 덜 소비하도록 effort를 낮추세요. 비용 제어 및 사고와 컨텍스트 윈도우를 참조하세요.

사고 설정 변경 후 캐시 적중이 감소함

이전에 캐시에 적중했던 요청에서 cache_read_input_tokens가 0으로 떨어집니다.

이는 사고 구성과 effort 수준(또는 그 기본값)이 캐시된 프롬프트 접두사의 일부이기 때문에 발생하며, 이 중 하나라도 변경하면 새 접두사가 시작됩니다. 사고 모드 전환, effort 값 변경, budget_tokens 변경은 모두 메시지 캐시 중단점을 무효화하며, 모델이 구성을 렌더링하는 위치에 따라 도구 및 시스템 프롬프트 중단점도 무효화할 수 있습니다.

대화를 공유하는 요청 전반에서 사고 구성과 effort 수준을 일정하게 유지하세요. 매개변수를 명시적으로 기본값으로 설정하는 것은 생략하는 것과 동일하며 무효화하지 않습니다. 사고와 프롬프트 캐싱을 참조하세요.

effort를 설정해도 사고가 변하지 않음

effort를 변경했지만 사고 빈도나 깊이가 그대로입니다.

이는 effort가 적응형 모드에서만 주요 사고 조절 수단이기 때문에 발생합니다. 확장 사고 전용 모델에서는 사고 깊이가 대신 budget_tokens로 설정됩니다.

해당 모델에서는 budget_tokens를 조정하거나, 모델이 어떤 모드로 실행되는지 확인하세요. 사고와 effort를 참조하세요. effort를 지원하는 유일한 확장 사고 전용 모델인 Claude Opus 4.5에서는 effort가 예산과 결합됩니다. 예산 규칙 및 튜닝을 참조하세요.

다음 단계