Solución de problemas de 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 (enviar los bloques de pensamiento devueltos de vuelta en solicitudes posteriores). La primera sección asocia cada modelo con sus configuraciones de pensamiento admitidas y las que rechaza; las secciones posteriores comienzan cada una desde un síntoma que observas, para que puedas relacionar un mensaje de error o una respuesta inesperada directamente con su causa y solución. Para saber cómo funciona el pensamiento, consulta la descripción general de Pensamiento.



Configuraciones que cada modelo rechaza

La mayoría de los errores de configuración de pensamiento son una discrepancia entre el valor de thinking.type en la solicitud y lo que el modelo admite. En los modelos actuales, el pensamiento se ejecuta como thinking: {type: "adaptive"}, y en los más recientes está activado de forma predeterminada. Algunos modelos anteriores usan en su lugar el pensamiento extendido, un modo manual heredado configurado como thinking: {type: "enabled", budget_tokens: N}.

El pensamiento extendido (thinking.type: "enabled" con budget_tokens) está obsoleto en los modelos Claude 4.6 (las solicitudes que lo usan siguen funcionando). 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 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 pensamiento adaptativo en su lugar.

La tabla enumera lo que admite cada modelo, cuál es su valor predeterminado y qué valores de thinking.type rechaza con un error 400; cualquier valor que no aparezca como rechazado se acepta.

¹ enabled y budget_tokens todavía funcionan en estos modelos pero están obsoletos; usa el pensamiento adaptativo en su lugar.
² Claude Opus 5 acepta "disabled" con effort high o inferior; combinarlo con effort xhigh o max devuelve un error 400. Esta restricción se aplica a Claude Opus 5 y modelos posteriores, y se verifica en cada solicitud.

Los modelos marcados como Siempre activado no pueden desactivar el pensamiento. Los modelos marcados como Activado tienen el pensamiento activado de forma predeterminada pero aceptan thinking: {type: "disabled"}.

Los modelos anteriores de Claude 4 (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 y Claude Mythos 5 no están disponibles bajo retención cero de datos.



Un error 400 dice 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 sucede porque el modelo que solicitaste ha eliminado el pensamiento extendido (consulta Configuraciones que cada modelo rechaza).

Cambia la solicitud a thinking: {type: "adaptive"} y dirige la profundidad del pensamiento con effort en lugar de budget_tokens. Migración al pensamiento adaptativo te guía a través de la conversión.



Un error 400 dice que "thinking.type.disabled" no es compatible

La solicitud falla con un error 400 cuyo 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 sucede en modelos donde el pensamiento está siempre activado: Claude Fable 5, Claude Mythos 5 y Claude Mythos Preview rechazan "disabled". En Claude Fable 5 y Claude Mythos 5, la sugerencia del texto del error de usar "thinking.type.enabled" tampoco aplica: esos modelos también la rechazan.

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

Un error 400 en "disabled" también puede ocurrir en Claude Opus 5, que acepta thinking: {type: "disabled"} solo con effort high o inferior: combinarlo con effort xhigh o max se rechaza. Reduce el nivel de effort o deja el pensamiento activado.



Un error 400 dice 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 sucede porque el modelo solo admite pensamiento extendido (consulta Configuraciones que cada modelo rechaza).

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



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

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

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

En conversaciones de múltiples turnos y de uso de herramientas, envías los mensajes anteriores del asistente, incluidos sus bloques thinking y redacted_thinking, de vuelta a la API, y la API verifica que lleguen sin modificar. Este error ocurre cuando el mensaje del asistente que envías de vuelta difiere del que devolvió la API, generalmente porque tu código filtra los bloques de contenido por tipo y descarta los bloques redacted_thinking, o reconstruye el mensaje del asistente en lugar de repetirlo tal cual.

Devuelve el turno del asistente textualmente, incluidos los bloques de pensamiento. Consulta Preservar los bloques de pensamiento para conocer las reglas, y el ejemplo completo de ida y vuelta en Pensamiento en flujos de trabajo de herramientas y múltiples turnos para ver el código correcto en cada SDK.



El campo thinking 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 está rellenado.

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

Establece display: "summarized" en tu configuración de pensamiento para recibir el texto de pensamiento resumido; consulta Controlar la visualización del pensamiento para conocer los valores predeterminados por modelo.



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 solicitudes que considera lo suficientemente simples como para responder directamente.

Si quieres que piense con más frecuencia o más profundidad, aumenta effort o dirígelo mediante prompting; consulta Dirigir la frecuencia con la que Claude piensa.



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

Una respuesta ocasionalmente 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, y en bucles agénticos el texto filtrado permanece en el historial de la conversación, por lo que los turnos posteriores también se ven afectados.

Esto sucede en Claude Opus 5 cuando el pensamiento está desactivado, más comúnmente en cargas de trabajo con uso intensivo de herramientas como la búsqueda. Las reglas de la indicación del sistema que instruyen al modelo a no pensar o no razonar 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 en su lugar. Si tu integración debe mantener el pensamiento desactivado, aplica las mitigaciones de prompting en Ejecución 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 sucede porque los tokens de pensamiento cuentan para max_tokens, por lo que una pasada de pensamiento larga 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 gaste menos en pensamiento; consulta Control de costos y El pensamiento y la ventana de contexto.



Los aciertos de caché caen después de cambiar la configuración de pensamiento

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

Esto sucede porque la configuración de pensamiento y el nivel de effort (o su valor predeterminado) forman parte del prefijo de prompt almacenado en caché, por lo que cambiar cualquiera de ellos inicia un nuevo prefijo: cambiar los modos de pensamiento, cambiar el valor de effort y cambiar budget_tokens invalidan los puntos de interrupción de caché de mensajes, y también pueden invalidar los puntos de interrupción de herramientas y de la indicación del sistema, dependiendo de dónde renderice el modelo la configuración.

Mantén constantes la configuración de pensamiento y el nivel de effort entre solicitudes que comparten una conversación; establecer un parámetro explícitamente en su valor predeterminado es equivalente a omitirlo y no invalida la caché. Consulta Pensamiento y almacenamiento en caché de prompts.



Establecer effort no cambia el pensamiento

Cambias effort pero la frecuencia o profundidad del pensamiento permanece igual.

Esto sucede porque effort es la palanca principal de pensamiento solo en el modo adaptativo. En los modelos que solo admiten pensamiento extendido, la profundidad del pensamiento se establece mediante budget_tokens en su lugar.

Ajusta budget_tokens en esos modelos, o verifica en qué modo se ejecuta tu modelo; consulta Pensamiento y effort. En Claude Opus 4.5, el único modelo de solo pensamiento extendido que admite effort, effort se compone con el presupuesto; consulta Reglas de presupuesto y ajuste.



Próximos pasos