Los desarrolladores descubrieron que el almacenamiento en caché de prompts (prompt-caching) de Claude puede fallar silenciosamente, cobrando tarifas premium mientras devuelve cero tokens en caché. Una ejecución de registros de una semana en un manejador de WhatsApp no mostró ninguna lectura de caché, pero la API facturó la función de caché, lo que redujo los costos de $1,890 a $406 por mes.

Por qué es importante este problema

El almacenamiento en caché de prompts tiene como objetivo reducir costos y acelerar las respuestas reutilizando una parte estática de un prompt (el "prefijo"). Cuando funciona, las aplicaciones de alto tráfico pueden ahorrar cientos de dólares en sus facturas mensuales. Cuando no funciona, los desarrolladores pagan por una función que nunca utilizan realmente, y el fallo silencioso no emite ningún error o advertencia que indique el problema.

Cómo se manifiesta el error

La API acepta una bandera cache-control y un prefijo, y luego informa cuántos tokens se leyeron de la caché. En el caso observado, cada solicitud devolvió un recuento de lectura de caché de cero. La llamada fue exitosa, no se lanzó ninguna excepción y la facturación reflejó el costo premium de la caché. El fallo es invisible a menos que registres explícitamente el recuento de lecturas.

Formas comunes en las que la caché se rompe

  • El prefijo es demasiado corto – Cada modelo de Claude define una longitud mínima de tokens para un prefijo que pueda almacenarse en caché. Haiku 4.5 necesita al menos 4,096 tokens; Sonnet 4.6 solo necesita 1,024. Enviar un prefijo más corto cumple con el formato de la solicitud, pero el servicio ignora la instrucción de caché.
  • Un byte volátil cambia – El almacenamiento en caché requiere una coincidencia exacta byte por byte. Agregar un elemento dinámico como una marca de tiempo, new Date(), o el correo electrónico de un usuario al inicio del prompt del sistema cambia la secuencia de bytes, lo que provoca que cada solicitud sea tratada como una escritura nueva y sin caché.
  • El orden de la lista de herramientas cambia – Las herramientas se anteponen al prompt. Si el array de herramientas se construye a partir de las claves de un objeto, el orden de iteración puede variar entre llamadas, alterando la disposición de los bytes y rompiendo la caché.

Soluciones que puedes aplicar hoy mismo

  • Validar la longitud del prefijo – Antes de enviar una solicitud, estima el recuento de tokens del prefijo frente al mínimo del modelo. Rechaza o rellena el prefijo si es insuficiente.
  • Registrar las lecturas de caché en cada llamada – Registra el campo "cache read tokens". Una racha de ceros es una señal clara de que no se está utilizando la caché.
  • Congelar los bytes iniciales del prompt – Mantén los datos dinámicos fuera del segmento en caché. Si debes incluir información específica del usuario, colócala después del prefijo en caché.
  • Sincronizar los identificadores del modelo – Asegúrate de que el ID del modelo utilizado en el enrutamiento coincida con el almacenado en tu tabla de caché; los IDs que no coinciden impiden la búsqueda en la caché.

El ángulo del costo

Para una aplicación que realiza miles de llamadas diarias, pasar de no usar caché a usarla puede reducir drásticamente los gastos mensuales, de aproximadamente $1,890 a $406 en el caso reportado. Incluso un tráfico modesto experimenta ahorros notables, y la mejora de rendimiento al reutilizar un prompt estático grande puede reducir la latencia.

Contrapunto

Sin embargo, la naturaleza silenciosa del fallo significa que la única forma de estar seguro de que no estás pagando de más es verificar el recuento de lecturas, algo que muchos pasan por alto.

Qué vigilar a continuación

  • Tableros de métricas – Añade un indicador para los tokens de lectura de caché junto al volumen de solicitudes.
  • Estabilidad en el orden de las herramientas – Si dependes de listas de herramientas generadas dinámicamente, considera ordenarlas de forma determinista antes de integrarlas en el prompt.

En resumen: El almacenamiento en caché de prompts de Claude no genera un error cuando ignora silenciosamente tu solicitud. Verifica la efectividad de la caché registrando los tokens leídos, aplica una longitud de prefijo adecuada y mantén inmutables los bytes iniciales del prompt. Solo entonces cosecharás los beneficios prometidos en costo y velocidad.