Cómo funciona el prompt caching de Claude — y cómo no pagar de más

El cache de prompt puede reducir el costo de llamadas repetidas de forma real — pero solo si el prefijo cacheado es idéntico byte a byte entre solicitudes. Esta página explica dónde poner el breakpoint de cache, cuándo preferir RAG sobre contexto largo, y cómo tratar los errores que devuelve la API.

Dónde poner el breakpoint de cache

Una llamada a la API se renderiza en este orden: tools, luego system, luego messages. Un breakpoint de cache en el último bloque del system prompt cachea todo el prefijo que vino antes de él — tools y system juntos — siempre que ese prefijo sea idéntico byte a byte entre solicitudes.

El error más común es colocar el breakpoint después del contenido que varía por solicitud: un texto de usuario único nunca se repite exactamente, así que cada llamada graba una entrada de cache nueva, pagando un recargo de escritura, y nunca logra un hit. Los datos variables van siempre al final, después de todo lo que se repite entre llamadas.

Un solo byte cambia y todo el cache se invalida

El cache no es aproximado: cualquier diferencia antes del breakpoint — una marca de tiempo en el system prompt, un orden distinto de tools — invalida todo lo que viene después de él. No existe un cache parcialmente válido; o el prefijo es idéntico y se reutiliza, o no lo es y se reprocesa desde cero.

Esto también decide la estrategia cuando las llamadas no son continuas: si el intervalo entre lotes de llamadas supera el TTL por defecto del cache, pero aún queda por debajo de una hora, existe una opción de TTL más largo pensada exactamente para ese caso — la alternativa a simplemente aceptar que el cache expira entre lotes.

429, 529 y 400 piden reacciones distintas

429 (límite de tasa) y 529 (sobrecarga) son errores transitorios: la respuesta correcta es reintentar con backoff exponencial, porque la misma solicitud tiene buena probabilidad de funcionar en el siguiente intento. Un 400, en cambio, es un bug en la solicitud — reintentar sin corregir nada solo reproduce el mismo error indefinidamente.

Un pipeline que ya maneja estos tres también debería leer los response headers de límite en cada llamada exitosa, para hacer throttling proactivo antes de topar con un 429 — en lugar de descubrir el límite recién después de haberlo superado.

Cuándo el contexto largo no es la respuesta correcta

El contexto largo funciona bien hasta que el corpus crece más allá de cualquier ventana de contexto disponible — cuando eso ocurre, RAG escala de un modo que simplemente ampliar el contexto no logra. El intercambio tiene un costo: RAG fragmenta el corpus en piezas recuperables, lo cual funciona bien para búsquedas puntuales, pero estorba justo en las preguntas que exigen síntesis entre varios documentos a la vez.

La decisión entre los dos no trata de cuál es "mejor" — trata del tamaño del corpus y del tipo de pregunta que realmente plantea el caso de uso.

Compaction: por qué el cliente todavía debe cuidar el estado

Cuando una conversación larga supera la ventana de contexto, Claude Code puede compactar el historial, resumiendo intercambios antiguos para liberar espacio. Esto preserva la continuidad de la conversación, pero no es automático del lado del cliente: en cada turno, sigue siendo responsabilidad de quien construye sobre la API reenviar correctamente el identificador de la sesión y el historial devuelto — o el estado se pierde aunque compaction esté habilitado.

Es el mismo principio de RAG frente a contexto largo, visto desde otro ángulo: gestionar lo que cabe en la ventana de contexto es una responsabilidad continua, no una configuración que se activa una vez y se olvida.