사고 문제 해결

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



각 모델이 거부하는 구성

대부분의 사고 구성 오류는 요청의 thinking.type 값과 모델이 지원하는 값 사이의 불일치입니다. 현재 모델에서 사고는 thinking: {type: "adaptive"}로 실행되며, 최신 모델에서는 기본적으로 켜져 있습니다. 일부 이전 모델은 대신 확장 사고를 사용하는데, 이는 thinking: {type: "enabled", budget_tokens: N}으로 구성되는 레거시 수동 모드입니다.

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

아래 표는 각 모델이 지원하는 것, 기본값, 그리고 400 오류로 거부하는 thinking.type 값을 나열합니다. 거부로 나열되지 않은 값은 모두 허용됩니다.

¹ enabled와 budget_tokens는 이 모델들에서 여전히 작동하지만 지원 중단되었습니다. 대신 적응형 사고를 사용하세요.
² Claude Opus 5는 effort가 high 이하일 때 "disabled"를 허용합니다. effort xhigh 또는 max와 결합하면 400 오류가 반환됩니다. 이 제한은 Claude Opus 5 및 이후 모델에 적용되며 각 요청마다 적용됩니다.

항상 켜짐으로 표시된 모델은 사고를 끌 수 없습니다. 켜짐으로 표시된 모델은 기본적으로 사고하지만 thinking: {type: "disabled"}를 허용합니다.

이전 Claude 4 모델(Claude Sonnet 4 및 Claude Opus 4)은 확장 사고만 지원합니다. 해당 모델의 가용성은 모델 지원 중단을 참조하세요. Claude Fable 5와 Claude Mythos 5는 제로 데이터 보존 하에서는 사용할 수 없습니다.



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로 사고 깊이를 조정하세요. 적응형 사고로 마이그레이션에서 변환 과정을 안내합니다.



400 오류가 "thinking.type.disabled"가 지원되지 않는다고 표시됨

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

"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.

이는 사고가 항상 켜져 있는 모델에서 발생합니다: Claude Fable 5, Claude Mythos 5, Claude Mythos Preview는 "disabled"를 거부합니다. Claude Fable 5와 Claude Mythos 5에서는 오류 텍스트가 제안하는 "thinking.type.enabled"도 적용되지 않습니다. 해당 모델들은 이것도 거부합니다.

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

"disabled"에 대한 400 오류는 Claude Opus 5에서도 발생할 수 있습니다. Claude Opus 5는 effort가 high 이하일 때만 thinking: {type: "disabled"}를 허용하며, effort xhigh 또는 max와 결합하면 거부됩니다. effort 수준을 낮추거나 사고를 켜 두세요.



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

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

adaptive thinking is not supported on this model

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

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



400 오류가 사고 블록을 수정할 수 없다고 표시됨

도구 결과를 반환하는 요청이 다음 내용을 포함하는 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 블록을 누락시키거나, 어시스턴트 메시지를 그대로 반환하는 대신 재구성하기 때문입니다.

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



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

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

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

요약된 사고 텍스트를 받으려면 사고 구성에서 display: "summarized"를 설정하세요. 모델별 기본값은 사고 표시 제어를 참조하세요.



일부 턴에서 사고 블록이 나타나지 않음

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

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

사고를 더 자주 또는 더 깊게 하려면 effort를 높이거나 프롬프팅으로 조정하세요. Claude가 사고하는 빈도 조정을 참조하세요.



텍스트 출력에 도구 호출 또는 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가 예산과 함께 작동합니다. 예산 규칙 및 조정을 참조하세요.



다음 단계