Solución de problemas del pensamiento

Esta página cubre los fallos más comunes al configurar el pensamiento o al hacer "round-tripping" (ida y vuelta) de bloques de pensamiento, es decir, enviar los bloques de pensamiento devueltos en solicitudes posteriores. La primera sección relaciona cada modelo con las configuraciones de pensamiento que admite y las que rechaza. Cada una de las secciones siguientes parte de un síntoma que observas, para que puedas relacionar un mensaje de error o una respuesta inesperada directamente con su causa y su solución. Para saber cómo funciona el pensamiento, consulta la descripción general de Pensamiento.

Compatibilidad con el pensamiento, valores predeterminados y configuraciones rechazadas por modelo

La mayoría de los errores de configuración del pensamiento se deben a una discrepancia entre el valor de thinking.type en la solicitud y lo que admite el modelo. En la mayoría de los modelos, el pensamiento se ejecuta como thinking: {type: "adaptive"}, y muchos lo tienen activado de forma predeterminada. Algunos modelos anteriores usan en su lugar el "extended thinking" (pensamiento extendido), un modo manual heredado que se configura como thinking: {type: "enabled", budget_tokens: N}; consulta pensamiento extendido.

El "extended thinking" (pensamiento extendido) (thinking.type: "enabled" con budget_tokens) está obsoleto en los modelos Claude 4.6 (las solicitudes que lo usan aún se completan correctamente). Claude 4.7 y los modelos posteriores no lo admiten y rechazan las solicitudes que lo usan, devolviendo un error 400. En Claude 4.5 y los modelos anteriores que admiten pensamiento, el pensamiento extendido es el único modo de pensamiento disponible. Claude Mythos Preview admite ambos modos. Donde ambos modos estén disponibles, usa el pensamiento adaptativo en su lugar.

La tabla indica lo que admite cada modelo, su valor predeterminado y qué valores de thinking.type rechaza con un error 400; cualquier valor que no figure como rechazado se acepta. Solo Claude Sonnet 5.5 acepta "between_tools", y lo acepta en lugar de "disabled".

¹ enabled y budget_tokens siguen funcionando en estos modelos, pero están obsoletos; usa el pensamiento adaptativo en su lugar.
² Claude Opus 5 y Claude Haiku 5.5 aceptan "disabled" con un nivel de effort (esfuerzo) high o inferior; combinarlo con un esfuerzo xhigh o max devuelve un error 400. En Claude Opus 5, esta restricción se aplica en cada solicitud. En Claude Haiku 5.5, un esfuerzo por mensaje que difiera del nivel vigente también devuelve un error 400.
³ Claude Sonnet 5.5 acepta "between_tools" con un esfuerzo high o inferior. Combinarlo con un esfuerzo xhigh o max devuelve un error 400, al igual que un esfuerzo por mensaje que difiera del nivel vigente.

Los modelos marcados como Siempre activado no pueden desactivar el pensamiento. Los modelos marcados como Activado piensan de forma predeterminada. Claude Opus 5, Claude Sonnet 5 y Claude Haiku 5.5 aceptan thinking: {type: "disabled"}. En Claude Sonnet 5.5, envía thinking: {type: "between_tools"} para desactivar el pensamiento inicial.

Los modelos Claude 4 anteriores (Claude Opus 4.1, Claude Sonnet 4 y Claude Opus 4) solo admiten pensamiento extendido. Consulta Obsolescencia de modelos para conocer su disponibilidad. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 y Claude Mythos 5 no están disponibles con retención de datos cero a menos que Anthropic lo autorice expresamente.

Un error 400 indica que "thinking.type.enabled" no es compatible

La solicitud falla con un error 400 cuyo mensaje dice:

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

Esto ocurre porque el modelo que solicitaste ya no admite el pensamiento extendido (consulta la tabla de configuración por modelo).

Cambia la solicitud a thinking: {type: "adaptive"} y controla la profundidad del pensamiento con effort en lugar de budget_tokens. Migrar al pensamiento adaptativo explica la conversión paso a paso.

Un error 400 después de enviar thinking: {type: "disabled"}

La solicitud falla con un error 400. En Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Opus 5.5 y Claude Mythos 5, el mensaje dice:

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

En Claude Mythos Preview, el único de estos modelos que acepta pensamiento extendido, el mensaje dice:

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

Esto ocurre porque el pensamiento siempre está activado en todos estos modelos (consulta la tabla de configuración por modelo).

Omite el parámetro thinking; estos modelos piensan sin ninguna configuración. Si tu objetivo era mantener el texto del pensamiento fuera de las respuestas, usa display: "omitted" en lugar de desactivar el pensamiento; consulta Controlar la visualización del pensamiento.

Un error 400 con "disabled" también puede ocurrir en Claude Opus 5 y Claude Haiku 5.5, que aceptan thinking: {type: "disabled"} solo con un esfuerzo high o inferior: combinarlo con un esfuerzo xhigh o max se rechaza. Reduce el nivel de esfuerzo o establece thinking en {"type": "adaptive"}.

En Claude Sonnet 5.5, thinking: {type: "disabled"} devuelve un error 400 en todos los niveles de esfuerzo. El mensaje dice:

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.

Para desactivar el pensamiento inicial en Claude Sonnet 5.5, envía thinking: {type: "between_tools"} en su lugar, con un esfuerzo high o inferior.

Un error 400 indica que "thinking.type.between_tools" no es compatible

La solicitud falla con un error 400 cuyo mensaje dice:

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

Esto ocurre porque solo Claude Sonnet 5.5 acepta thinking: {type: "between_tools"} (consulta la tabla de configuración por modelo).

Envía between_tools solo a Claude Sonnet 5.5. En otros modelos, omite thinking o usa un valor de thinking.type que la tabla no indique como rechazado.

Un error 400 indica que un nivel de esfuerzo no es compatible cuando el pensamiento está desactivado

En Claude Sonnet 5.5, una solicitud con thinking: {type: "between_tools"} y un esfuerzo xhigh o max falla con un error 400 cuyo mensaje dice:

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

Esto ocurre porque Claude Sonnet 5.5 acepta between_tools solo con un esfuerzo high o inferior. El mensaje dice que el pensamiento está desactivado porque between_tools no tiene pensamiento inicial, aunque la solicitud no haya enviado "disabled". El mensaje indica el nivel que envió la solicitud.

Reduce el esfuerzo a high o inferior. Para ejecutar con xhigh o max, usa el pensamiento adaptativo: omite el campo thinking o envía thinking: {"type": "adaptive"}. Eso es lo que el mensaje quiere decir con "enable thinking". Claude Sonnet 5.5 rechaza "enabled" con un error 400.

Claude Haiku 5.5 devuelve el mismo mensaje cuando una solicitud envía thinking: {type: "disabled"} con un esfuerzo xhigh o max. Acepta "disabled" solo con high o inferior. Reduce el esfuerzo o establece thinking en {"type": "adaptive"}.

Un error 400 indica que el esfuerzo no puede cambiar cuando el pensamiento está desactivado

En Claude Sonnet 5.5, una solicitud con thinking: {type: "between_tools"} cuyo esfuerzo por mensaje cambia el nivel falla con un error 400 cuyo mensaje dice:

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.

El mensaje dice que el pensamiento está desactivado porque between_tools no tiene pensamiento inicial. Con between_tools, el esfuerzo no puede cambiar a mitad de la conversación: un output_config.effort por mensaje que difiera del nivel vigente devuelve un error 400. messages.N es la posición del mensaje que estableció el nuevo nivel.

Elimina ese esfuerzo por mensaje o establécelo en el nivel vigente. Para variar el esfuerzo en cada turno, usa el pensamiento adaptativo: omite el campo thinking o envía thinking: {"type": "adaptive"}. Eso es lo que el mensaje quiere decir con "enable thinking".

Claude Haiku 5.5 devuelve el mismo mensaje cuando una solicitud con thinking: {type: "disabled"} establece un esfuerzo por mensaje que difiere del nivel vigente. Elimina ese esfuerzo por mensaje o establece thinking en {"type": "adaptive"} para variar el esfuerzo en cada turno.

Un error 400 indica que el pensamiento adaptativo no es compatible

La solicitud falla con un error 400 cuyo mensaje dice:

adaptive thinking is not supported on this model

Esto ocurre porque el modelo solo admite el pensamiento extendido (consulta la tabla de configuración por modelo).

Usa thinking: {type: "enabled", budget_tokens: N} en su lugar. Consulta Pensamiento extendido para ver la configuración.

Un error 400 indica que los bloques de pensamiento no se pueden modificar

Una solicitud que devuelve resultados de herramientas falla con un error 400 invalid_request_error cuyo mensaje contiene:

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

En las conversaciones de múltiples turnos y de uso de herramientas, envías de vuelta a la API los mensajes anteriores del asistente, incluidos sus bloques thinking y redacted_thinking, y la API verifica que lleguen sin modificaciones. Este error ocurre cuando el mensaje del asistente que envías de vuelta difiere del que devolvió la API. Lo más habitual es que tu código filtre los bloques de contenido por tipo y descarte los bloques redacted_thinking, o que reconstruya el mensaje del asistente en lugar de reenviarlo tal cual.

Reenvía el turno del asistente textualmente, incluidos los bloques de pensamiento. Consulta Conservar los bloques de pensamiento para conocer las reglas. Para ver código correcto en todos los SDK, consulta el ejemplo completo de ida y vuelta en Pensamiento en flujos de trabajo con herramientas y de múltiples turnos.

Un error 400 indica que la firma de un bloque de pensamiento no es válida

Una solicitud a Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 o Claude Haiku 5.5 que reenvía bloques de pensamiento anteriores falla con un error 400 invalid_request_error cuyo mensaje dice:

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

Si la solicitud no envió el encabezado beta thinking-binding-controls-2026-08-01, el mensaje añade That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

El mensaje suele terminar con una oración que indica qué cambió: la indicación del sistema system, la lista tools, el primer mensaje o bloque que difiere, contenido que falta o es nuevo, o un bloque de pensamiento anterior que falta o está fuera de orden. Esa oración está pensada para personas y registros. Su redacción puede cambiar, así que no la compares en el código.

Si el mensaje termina después de Invalid `signature` in `thinking` block, la firma en sí no se verificó: se truncó, se alteró o se envió vacía, y prefix_mismatch_behavior no se aplica. El texto de pensamiento editado devuelve un error diferente. Consulta Un error 400 indica que los bloques de pensamiento no se pueden modificar.

En Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 5.5, la API acepta un bloque de pensamiento reenviado solo mientras la indicación del sistema system, tools y los mensajes que lo precedieron no cambien. Consulta Mantener el prefijo sin cambios. El error significa que algo anterior en la conversación cambió entre solicitudes: un turno editado, reordenado o eliminado, un recordatorio por turno que se inyectó y luego se eliminó, una indicación del sistema system o un arreglo tools reconstruidos, o una compactación del lado del cliente que conservó textualmente los turnos recientes y su pensamiento. La comprobación se aplica a las cuentas nuevas creadas a partir del 31 de agosto de 2026 y a cualquier solicitud que establezca thinking.block_binding.prefix_mismatch_behavior. La compactación y la edición de contexto del lado del servidor nunca la activan.

Para corregirlo, mantén el historial en modo de solo anexar: devuelve los turnos anteriores exactamente como se enviaron y recibieron, añade instrucciones con un mensaje del sistema a mitad de la conversación en lugar de editar system o tools, y deja que la edición de contexto o la compactación del lado del servidor se encarguen de cualquier recorte. Reintentar el mismo cuerpo de solicitud no elimina el error. Para continuar esta solicitud sin el razonamiento invalidado, envía el encabezado beta thinking-binding-controls-2026-08-01 y establece thinking.block_binding.prefix_mismatch_behavior en "drop_block". Como alternativa, elimina todos los bloques thinking y redacted_thinking del historial (como mínimo el bloque indicado y todos los posteriores, en ese turno y en todos los turnos siguientes), deja en su lugar los demás bloques de cada turno y reintenta una vez. En Claude Sonnet 5.5 y Claude Haiku 5.5, block_binding solo funciona con thinking: {"type": "adaptive"}. Con between_tools en Claude Sonnet 5.5, o thinking: {"type": "disabled"} en Claude Haiku 5.5, mantén el historial en modo de solo anexar, o elimina los bloques de pensamiento a partir del turno editado.

Un bloque de un modelo que el modelo de destino no puede leer nunca produce este error: la API lo descarta y, con el encabezado beta, lo informa en input_transformations.

El campo de pensamiento está vacío en la respuesta

La respuesta contiene bloques thinking, pero su campo thinking es una cadena vacía y solo el campo signature tiene contenido.

Esto ocurre porque display tiene como valor predeterminado "omitted" en los modelos más recientes, lo que devuelve los bloques de pensamiento sin su texto.

Establece display: "summarized" en tu configuración de pensamiento para recibir el texto resumido del pensamiento. Consulta Controlar la visualización del pensamiento para ver los valores predeterminados por modelo. Algunos modelos escriben breves líneas de estado entre llamadas a herramientas. Si solo quieres esas líneas y no el razonamiento, establece display: "updates" (beta) en su lugar. Consulta Actualizaciones de progreso entre llamadas a herramientas.

Un bloque cuyo campo thinking está vacío sigue estando completo, porque la signature contiene el razonamiento. Reenvíalo con el turno como cualquier otro. Consulta Enviar los turnos del asistente de vuelta exactamente como se devolvieron.

No aparece ningún bloque de pensamiento en algunos turnos

Algunas respuestas no contienen ningún bloque thinking, aunque el pensamiento esté configurado.

Esto es normal en el modo adaptativo: Claude omite el pensamiento en las solicitudes que considera lo bastante simples como para responderlas directamente.

Si quieres que piense con más frecuencia o más a fondo, aumenta effort u oriéntalo mediante el prompt. Consulta Orientar la frecuencia con la que Claude piensa.

Un tool_choice forzado ({"type": "any"} o una herramienta específica) tampoco devuelve ningún bloque thinking: la respuesta comienza con la llamada a la herramienta. Para permitir que el modelo piense antes de llamar a una herramienta, usa tool_choice: {"type": "auto"} e indica en el prompt cuándo usar la herramienta.

Aparecen llamadas a herramientas o etiquetas XML en la salida de texto

En ocasiones, una respuesta escribe una llamada a herramienta en su texto en lugar de emitir un bloque tool_use, o incluye <thinking> u otras etiquetas XML internas en su texto visible. Una llamada a herramienta filtrada nunca se ejecuta. Además, en los bucles agénticos el texto filtrado permanece en el historial de la conversación, por lo que también afecta a los turnos posteriores.

Esto ocurre en Claude Opus 5 cuando el pensamiento está desactivado, sobre todo en cargas de trabajo con uso intensivo de herramientas, como la búsqueda. Las reglas de la indicación del sistema que le piden al modelo que no piense o que no razone aumentan la filtración de etiquetas.

Vuelve a activar el pensamiento (el valor predeterminado) y usa niveles de effort más bajos para controlar el costo de tokens. Si tu integración debe mantener el pensamiento desactivado, aplica las mitigaciones de prompting de Ejecutar con el pensamiento desactivado.

La respuesta se detiene con stop_reason: "max_tokens"

La respuesta termina con stop_reason: "max_tokens", a menudo con un bloque de texto truncado o ausente.

Esto ocurre porque los tokens de pensamiento cuentan para max_tokens. Un pensamiento largo puede consumir el presupuesto antes de que se complete la respuesta de texto.

Aumenta max_tokens para dejar espacio tanto para el pensamiento como para el texto, o reduce effort para que Claude dedique menos al pensamiento. Consulta Control de costos y El pensamiento y la ventana de contexto.

Los aciertos de caché disminuyen después de cambiar la configuración del pensamiento

cache_read_input_tokens cae a cero en solicitudes que antes acertaban en la caché.

Esto ocurre porque la configuración del pensamiento y el nivel de esfuerzo (o su valor predeterminado) forman parte del prefijo del prompt almacenado en caché. Cambiar cualquiera de ellos inicia un nuevo prefijo. Cambiar de modo de pensamiento, cambiar el valor de esfuerzo o cambiar budget_tokens invalida los puntos de interrupción de caché de los mensajes. Según dónde represente el modelo la configuración, también puede invalidar los puntos de interrupción de las herramientas y de la indicación del sistema.

Mantén constantes la configuración del pensamiento y el nivel de esfuerzo en las solicitudes que comparten una conversación. Establecer un parámetro explícitamente en su valor predeterminado equivale a omitirlo y no invalida la caché. Consulta Pensamiento y almacenamiento en caché de prompts.

Configurar el esfuerzo no cambia el pensamiento

Cambias effort, pero la frecuencia o la profundidad del pensamiento siguen siendo las mismas.

Esto ocurre porque el esfuerzo es el control principal del pensamiento solo en el modo adaptativo. En los modelos que solo admiten pensamiento extendido, la profundidad del pensamiento se establece con budget_tokens.

Ajusta budget_tokens en esos modelos, o comprueba en qué modo se ejecuta tu modelo. Consulta Pensamiento y esfuerzo. Claude Opus 4.5 es el único modelo de solo pensamiento extendido que admite el esfuerzo, y en él el esfuerzo se combina con el presupuesto. Consulta Reglas y ajuste del presupuesto.

Próximos pasos