Verificaciones de prefijo en bloques de pensamiento

Cada solicitud que devuelve “thinking blocks” (bloques de pensamiento) a un modelo con “preserved thinking” (pensamiento preservado) pasa por una “prefix check” (verificación de prefijo). Una verificación de prefijo falla si system, tools o un mensaje anterior cambiaron después de que Claude produjera un bloque. También falla si un bloque de pensamiento situado entre otros se omitió o se movió.

No superar la verificación de prefijo puede o no dar como resultado un error 400, según el modelo, así que maneja ambos casos.

A quién afecta la verificación de prefijo

No tienes nada que cambiar si se cumple una de estas condiciones:

• Claude Code, claude.ai o Claude Managed Agents gestiona tu historial de conversación.
• El Claude Agent SDK gestiona el historial, y la indicación del sistema que le das al SDK se mantiene igual.
• Tu código sigue los tres hábitos de una integración “append-only” (de solo anexar), y nada reescribe sus solicitudes por el camino.
• No llamas a ningún modelo con pensamiento preservado.

Si tus solicitudes pasan por una biblioteca, un proxy o un gateway, compara lo que envía con lo que enviaste tú. Si ejecutas uno, consulta Bibliotecas, proxies y gateways para saber qué debe dejar pasar.

Qué debe mantenerse igual y por qué

Haz que tu integración sea de solo anexar. Tres hábitos lo logran:

1. Devuelve cada turno del asistente exactamente como lo devolvió la API, incluidos los bloques de pensamiento cuyo texto está vacío.
2. Construye system y tools una vez por cada conversación, y envía esa copia cada vez.
3. Coloca cada actualización en un mensaje nuevo al final, y déjala ahí.

El razonamiento de cada bloque de pensamiento trata exactamente sobre lo que vino antes de él: system, tools y cada mensaje anterior. Ese contenido es el prefijo del bloque, y es lo que compara la verificación de prefijo.

La verificación de prefijo es similar al “prompt caching” (almacenamiento en caché de prompts), excepto que un cambio invalida el pensamiento posterior a él en lugar de solo perder la caché.

Toma como ejemplo una aplicación que pone la fecha de hoy en su indicación del sistema. A medianoche la fecha cambia, y también el prefijo del pensamiento que ya está en la conversación. Ese pensamiento se vuelve inválido, y la siguiente solicitud puede fallar. Una aplicación de solo anexar mantiene la indicación del sistema tal como estaba, e indica la nueva fecha en un mensaje al final.

Un cambio invalida solo el pensamiento que ya le sigue. El pensamiento anterior a él y el pensamiento que Claude produce después siguen siendo válidos.

Si tu código cambia la indicación del sistema, las herramientas o el historial

Otras causas, como omitir bloques de pensamiento cuyo texto está vacío o reconstruir una conversación guardada, tienen sus propias soluciones: consulta Cambia herramientas o instrucciones sin fallar la verificación de prefijo. Para encontrar la tuya, haz que un agente revise tu código.

Qué hace cada modelo cuando la verificación de prefijo falla

En la Claude API y en algunas plataformas en la nube, el resultado de no superar la verificación de prefijo con prefix_mismatch_behavior sin establecer depende del modelo:

Donde la tabla dice “Posible error 400”, hay dos casos: una solicitud que no supera la verificación de prefijo podría recibir un error 400 o ningún error. Cuando no se devuelve ningún error, los bloques que no superan la verificación de prefijo llegan al modelo. Claude los lee como cualquier otra entrada, se te factura por ellos, y Claude trabaja a partir de un razonamiento sobre contenido que ha cambiado desde entonces.

En esos modelos, puedes comprobar qué caso obtiene una solicitud, pero maneja ambos casos.

Los elementos de Message Batches que dejan prefix_mismatch_behavior sin establecer no reciben ningún error, y la API puede omitir los bloques que no superan la verificación de prefijo.

Maneja ambos casos

Para obtener un único resultado en cada solicitud, haz que tu integración sea de solo anexar o establece prefix_mismatch_behavior. De lo contrario, tu código debe manejar ambos comportamientos.

• De solo anexar: con los tres hábitos, tu código no hace que una solicitud falle la verificación de prefijo.
• La configuración: con "error" en cada solicitud, cada fallo es un error 400, y lo capturas en el código.
• Ambos comportamientos: si dejas la configuración sin establecer, captura el error 400 y vigila el pensamiento que no superó la verificación de prefijo y llegó a Claude.

Después de un error 400, envía "drop_block" en las solicitudes posteriores de esa conversación para recuperarte. Tiene un costo: consulta Lo que cuesta omitir el pensamiento. No lo envíes en todas tus conversaciones para ocultar errores.

Detalles técnicos

Cómo funciona la verificación de prefijo

Los modelos con pensamiento preservado registran una huella del prefijo de cada bloque de pensamiento en su signature. La referencia de la API llama a la verificación de prefijo la verificación de conversación, y el error 400 indica que un bloque que no supera la verificación de prefijo is bound to a different conversation.

Qué modelos ejecutan la verificación de prefijo

La verificación de prefijo se ejecuta en la Claude API y en algunas plataformas en la nube. Verifica los bloques de pensamiento que produjo un modelo con pensamiento preservado, en solicitudes a uno de esos modelos. En la Claude API, otros modelos, como Claude Opus 5, no la ejecutan, y no cubre sus bloques.

Qué cuenta como un cambio

• Cada bloque se verifica contra su propio registro. La API compara lo que hay antes de un bloque en esta solicitud con lo que su firma registró cuando Claude lo produjo. Tu última solicitud no interviene. La verificación de prefijo solo observa el contenido, no las sesiones, los ID ni los usuarios. El mismo contenido en una nueva solicitud o en una bifurcación supera la verificación de prefijo.
• La verificación de prefijo compara lo que enviaste, no lo que leyó Claude. La compactación en un umbral de tokens y la edición de contexto solo cambian lo que lee Claude, así que nunca cuentan. Después de un bloque de compactación por umbral, la API compara solo los mensajes a partir de ese bloque, además de system y tools. La compactación bajo demanda tiene sus propias condiciones: consulta Condiciones para que el pensamiento conservado siga siendo válido. Para un archivo enviado por URL y, en la Claude API, una lista de herramientas MCP, la API compara en su lugar lo que obtuvo.
• El pensamiento que envías debe ser una secuencia ininterrumpida. Los bloques de pensamiento no se comparan como contenido. Pero cada uno que envías, aparte del primero, debe tener el mismo bloque de pensamiento anterior que cuando Claude lo produjo. Así que puedes omitir el más antiguo, el más reciente o todos ellos, pero no uno intermedio.

Un cambio puede ser tan pequeño como una palabra de la descripción de una herramienta. Cambiar, insertar, mover o eliminar un mensaje anterior cuenta, sea cual sea su rol. También cuenta cambiar el texto que precede a un bloque de pensamiento en su propio mensaje.

Qué no cuenta

Establece prefix_mismatch_behavior

El encabezado beta thinking-binding-controls-2026-08-01 agrega la configuración thinking.block_binding.prefix_mismatch_behavior y el array input_transformations de la respuesta.

Los bloques que no superan la verificación de prefijo siguen siendo inválidos en cada solicitud posterior que los envíe, mientras el cambio siga vigente. La configuración actúa solo sobre la solicitud que la lleva. Con el pensamiento desactivado ("disabled" o "between_tools"), enviarla produce un error 400 en todos los modelos.

La siguiente solicitud establece prefix_mismatch_behavior en "drop_block". En un primer turno no hay pensamiento que devolver, así que input_transformations se devuelve vacío:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(f"Input transformations: {len(response.input_transformations or [])}")

Vigila el tráfico de producción

Con prefix_mismatch_behavior sin establecer, una solicitud que no supera la verificación de prefijo podría no recibir ningún error en algunos modelos. Los bloques de pensamiento que no la superaron llegan entonces al modelo. Para encontrar esos bloques en el tráfico de producción, envía el encabezado beta thinking-binding-controls-2026-08-01, deja la configuración sin establecer y registra el array input_transformations de cada respuesta. El encabezado agrega ese array y no cambia lo que recibe el modelo.

Cada uno de esos bloques obtiene su propia entrada thinking_mismatch_allowed en ese array. Una entrada tiene este aspecto:

{
  "input_transformations": [
    {
      "type": "thinking_mismatch_allowed",
      "path": "messages.1.content.0",
      "reason": "prefix_binding_mismatch"
    }
  ]
}

Para encontrar el cambio, consulta Encuentra lo que cambió tu código.

Comprueba qué caso obtienes

En algunos modelos, una solicitud que no supera la verificación de prefijo podría recibir el error 400 o ningún error. Esta prueba muestra cuál recibe una solicitud:

1. Toma una conversación que contenga un bloque de pensamiento de uno de esos modelos. Cambia o agrega la indicación del sistema (system). El bloque entonces no supera la verificación de prefijo, porque la indicación del sistema cambió después de que Claude produjera el bloque.
2. Envíala al mismo modelo con el encabezado beta thinking-binding-controls-2026-08-01, y deja prefix_mismatch_behavior sin establecer.

La respuesta es una de estas:

• Un error 400 que dice bound to a different conversation: La solicitud recibió el error 400.
• Una respuesta 200 cuyo array input_transformations tiene entradas thinking_mismatch_allowed: La solicitud no recibió ningún error. Cada entrada nombra un bloque de pensamiento que no superó la verificación de prefijo y llegó a Claude.
• Una respuesta 200 cuyo array input_transformations está vacío: Ningún bloque falló la verificación de prefijo, así que la prueba no muestra nada. Comprueba que la conversación contenga un bloque de pensamiento de ese modelo.

El resultado describe esa única solicitud y no garantiza nada sobre las siguientes, así que escribe tu código para manejar ambos casos.

Próximos pasos