Un cache miss en Claude Code suele significar que el prefijo reutilizable no paso por la lectura barata de cache. El turn se vuelve caro porque esa parte del contexto fue procesada de nuevo, escrita de nuevo en prompt cache o solo coincidio parcialmente. Los output tokens siguen siendo otra parte normal del coste.
A fecha 24 de mayo de 2026, la matematica de Anthropic explica el 12.5x que circula en muchas conversaciones tecnicas. Una escritura de cache de 5 minutos cuesta 1.25x el input base, mientras que una lectura de cache cuesta 0.1x para los mismos tokens. 1.25 / 0.1 = 12.5. Eso es una comparacion entre escritura y lectura, no una tarifa oficial separada por "cache miss".
Antes de cambiar tu flujo, ponle nombre a la ruta que genero el numero: uso de suscripcion, facturacion con API key, estimacion de Agent SDK, Bedrock, Vertex, Foundry o gateway. Luego compara cache_creation_input_tokens, cache_read_input_tokens, modelo, cambios de MCP, comandos como /compact, version de Claude Code, marcas de tiempo y la superficie de facturacion que corresponde a esa ruta. Sin esa disciplina, un invalidator normal parece un bug.
Respuesta rapida: prueba la ruta antes de tocar el cache
| Pregunta | Respuesta corta | Prueba que debes recoger |
|---|---|---|
| Un cache miss es una tarifa separada? | No. Significa que el prefijo no se leyo barato desde cache y tuvo que procesarse o escribirse otra vez. | Campos de creation/read dentro de la misma ruta. |
| Por que aparece 12.5x? | Escritura de 5 minutos a 1.25x dividida por lectura a 0.1x para el mismo volumen. | Pagina actual de precios de Anthropic y campos de usage. |
| Que revisar primero? | El propietario de la ruta: suscripcion, API key, SDK, proveedor cloud o gateway. | /status, /cost, Claude Console, Usage and Cost API, invoice del proveedor. |
| Cuando es sospechoso? | Cuando turns parecidos repiten high creation y low read con modelo, MCP, ruta y timing estables. | Timestamps, version, modelo, lista MCP y deltas de campos. |
| Que no hacer primero? | No compactar, cambiar provider o declarar bug sin identificar el invalidator. | Nombrar el cambio que pudo alterar el prefijo. |
Si la duda real es que ruta esta activa, usa primero Claude Code API key vs subscription billing. Si el problema mas amplio es contexto pesado por demasiados MCP o definiciones de herramientas, el camino correcto es Claude Code MCP context overload. El cache miss explica la economia de entrada de un turn; no sustituye un diagnostico de limites, plan o factura del proveedor.
El 12.5x es matematica entre write y read
La pagina de precios de Claude API separa input normal, cache write, cache read y output. La estructura publica actual dice que una escritura de cache de 5 minutos cuesta 1.25x del input base, una escritura de 1 hora cuesta 2x y una lectura de cache cuesta 0.1x.
text5-minute cache write / cache read = 1.25 / 0.1 = 12.5 1-hour cache write / cache read = 2.0 / 0.1 = 20
Esa formula solo debe usarse cuando comparas el mismo volumen de prefijo. Si ayer ese bloque fue leido desde cache y hoy se escribio, el contraste explica por que el turn parece caro. Pero la formula no demuestra una linea de recargo llamada cache miss fee, ni demuestra por si sola un bug de Claude Code.
Una nueva conversacion, un cambio de modelo, conectar o desconectar MCP servers, un intervalo largo de inactividad, actualizar Claude Code o ejecutar /compact pueden producir una nueva cache creation esperable. El riesgo aumenta cuando el prefijo es grande: historial largo, contexto de proyecto, tool results, definiciones MCP, subagents, file packs o system prompt extenso. Un miss pequeno puede ser ruido; una creation grande y repetida en turns parecidos merece investigacion.
Libro de tokens: el total no cuenta toda la historia
No diagnostiques un turn caro solo con total tokens. El total mide tamano, pero no explica por que el coste subio. Separa la lectura por clases.
| Medidor | Que significa | Como usarlo |
|---|---|---|
| Input tokens normales | Entrada procesada por el modelo sin lectura barata de cache. | Coste base cuando no hay cache o solo coincide una parte. |
cache_creation_input_tokens | Tokens escritos en prompt cache o procesados como creation. | Una escritura esperada puede ser normal; creation alta repetida es la senal. |
cache_read_input_tokens | Tokens leidos desde una entrada de cache existente. | Read alto frente a creation suele indicar reutilizacion correcta. |
| Output tokens | Respuesta generada por el modelo. | El ahorro de input no vuelve gratis el output. |
| Uso de suscripcion | Ventanas de plan, seat usage, reset y limites incluidos. | No se compara directamente con una factura API. |
/cost y campos del SDK | Estimaciones locales o de cliente. | Sirven para tendencia, pero son mas debiles que la factura. |
| Console, Usage and Cost API, invoice de proveedor | Superficie autoritativa para su ruta. | Prueba final de gasto y soporte. |
La documentacion de Agent SDK cost tracking trata total_cost_usd y costUSD como estimaciones. Eso no las invalida: son utiles para detectar una sesion descontrolada y comparar turns similares. Pero para una decision financiera vuelve a Claude Console, Usage and Cost API, factura cloud, registros del gateway o la superficie de suscripcion correspondiente.
Cuando no sabes que ruta esta activa, empieza con una comprobacion minima:
bashclaude /status /cost
/status ayuda a identificar cuenta o ruta. /cost puede servir para monitorizar gasto de estilo API, pero la prueba de facturacion pertenece a la ruta que produjo esa ejecucion.
Que acciones invalidan el cache en Claude Code
La documentacion de Claude Code prompt caching se basa en prefix matching. Si cambia una parte temprana de la solicitud, lo que viene despues puede dejar de coincidir aunque el texto del usuario parezca parecido. Por eso la pregunta no es solo "cuantos tokens", sino "que cambio justo antes del turn caro".
| Accion reciente | Riesgo | Siguiente comprobacion |
|---|---|---|
| Cambiar de modelo | Alto | Compara model y timestamp antes y despues del spike. |
| Conectar o desconectar MCP servers | Alto | Las tool definitions pueden cambiar el prefijo temprano. |
| Denegar una herramienta completa | Alto | Whole-tool denial cambia el contexto de herramientas disponibles. |
Ejecutar /compact | Alto | Reescribe el conversation context y puede romper reuse. |
| Actualizar Claude Code | Alto | La version puede cambiar prompt shape o cache scope. |
| Cambiar provider, API route o gateway | Alto | Cambian cache scope y billing owner. |
| Mucho tiempo inactivo | Medio | El TTL pudo expirar antes del siguiente read. |
| Subagents, forks, worktrees o directorios | Medio | El contexto puede dividirse por path, proceso o agent scope. |
| Editar archivos | Menor | Agrega contexto, pero no siempre cambia el prefijo temprano. |
| Cambiar output style o permission mode | Menor | Registralo si coincide con el momento del spike. |
/recap o rewind | Menor | Puede ser util, pero verifica los campos de usage. |
La interpretacion conservadora evita falsas alarmas. Una cache write despues de un cambio significativo puede ser esperada. Una cache creation repetida con la misma ruta, modelo, MCP setup, intervalo corto y contexto parecido tiene mucho mas peso diagnostico.
Evidencia por ruta: no mezcles cinco contratos
Una misma sesion local de Claude Code puede mostrar numeros que vienen de contratos distintos. Subscription login, API key, Agent SDK, cloud provider y gateway pueden exponer usage o cost, pero no son el mismo contador.
| Ruta | Que puede significar el numero | Prueba mas fuerte |
|---|---|---|
| Claude subscription login | Uso de plan o seat, ventanas de limite, reset timing e included usage. | Lenguaje de Help Center, estado de cuenta, /status, mensajes del plan. |
| Claude API key | Facturacion API pay-as-you-go por tokens. | Claude Console, Usage and Cost API, project billing settings. |
| Agent SDK | Usage y cost estimate desde mensajes del SDK. | Campos SDK mas Console o Usage and Cost API. |
| Bedrock, Vertex, Foundry | Uso de modelo por proveedor, limites de cache y factura del proveedor. | Invoice cloud y logs de request de esa ruta. |
| Gateway | Registros del gateway y pass-through hacia upstream. | Logs del gateway y upstream billing si esta disponible. |
Claude Code costs y el articulo de Help Center sobre uso y limites importan porque separan subscription usage de API billing. No uses un mensaje de limite de suscripcion para probar gasto API. No uses una estimacion de SDK para probar que se cobro un asiento de suscripcion.
Si el sintoma real es una interrupcion por ventana de plan, mira Claude Code rate limit o Claude Code rate limit reached. La matematica de cache ayuda a explicar consumo de input, pero no es todo el playbook de recuperacion de cuota.
Orden de correccion: cambia poco y mide el siguiente turn
Un turn caro no exige redisenar todo el flujo. Cambia una variable, verifica y conserva la comparacion en la misma ruta.
- Identifica la ruta. Suscripcion, API key, SDK estimate, provider route o gateway route.
- Lee los campos de cache. Compara
cache_creation_input_tokensycache_read_input_tokensen varios turns parecidos. - Nombra el invalidator. Modelo, MCP, whole-tool denial,
/compact, upgrade, provider, TTL, subagent, fork, worktree o directory scope. - Estabiliza el prefijo temprano. No cambies modelo ni MCP setup a mitad de la misma tarea sin razon.
- Separa trabajos no relacionados con
/clear. Mezclar tareas hace el prefijo grande e inestable. - Usa
/compacten cortes naturales. Sirve cuando la conversacion es demasiado grande, pero no es el primer remedio para un miss. - Evalua 1-hour TTL por cadence. Tiene multiplicador de escritura mayor y solo compensa si los read posteriores lo recuperan.
- Verifica el siguiente turn parecido. Una correccion real reduce repeated creation y aumenta read con modelo y ruta estables.
Si cambias modelo, reduces MCP, compactas y cambias gateway al mismo tiempo, el resultado puede bajar pero no sabras por que. La trazabilidad importa mas que el gesto grande.
Paquete para un spike sospechoso
No escales con una frase vaga. Prepara datos que permitan comparar la misma ruta y la misma forma de contexto.
| Evidencia | Por que importa |
|---|---|
| Timestamp y zona horaria | Permite alinear usage records e invoices. |
| Version de Claude Code | Un upgrade puede cambiar prompt shape. |
| Modelo | El cambio de modelo es un invalidator conocido. |
| Ruta activa | Suscripcion, API key, SDK, provider y gateway no se mezclan. |
| Lista MCP antes y despues | Connect/disconnect puede cambiar el prefijo temprano. |
| Cambios de permisos de herramientas | Whole-tool denial cambia tool context. |
/compact, /clear, /recap, rewind history | Acciones que alteran conversation shape. |
cache_creation_input_tokens y cache_read_input_tokens | Prueba central de write frente a read. |
| Turns parecidos con hit y miss | Una comparacion pesa mas que una captura aislada. |
| Billing surface | Console, Usage and Cost API, invoice del proveedor o subscription usage. |
Una cache write despues de un cambio de contexto no basta para acusar un bug. Creation alta repetida con ruta, modelo, MCP setup, timing y contexto similares si justifica un support packet.
Preguntas frecuentes
Un cache miss en Claude Code es una tarifa separada?
No. Es mejor leerlo como el lado caro de prompt caching: el prefijo reutilizable no fue leido desde cache al precio bajo y se proceso o escribio de nuevo. Mira token class y ruta, no una linea de recargo.
De donde sale el 12.5x?
Sale de los multiplicadores actuales de Anthropic. Una escritura de cache de 5 minutos cuesta 1.25x input base y una lectura cuesta 0.1x. Para los mismos tokens, 1.25 / 0.1 = 12.5.
Que campos prueban el comportamiento de cache?
Empieza con cache_creation_input_tokens y cache_read_input_tokens. Creation alta con read bajo significa que el prefijo no se reutilizo barato. La repeticion en turns parecidos es la senal fuerte.
/compact reduce el coste?
A veces, pero no es una correccion universal. Puede reducir una conversacion demasiado grande en un corte natural, aunque tambien reescribe contexto y puede romper reuse.
Debo usar 1-hour TTL?
Solo si la ruta lo soporta y el patron de reutilizacion compensa el write mas caro. Un TTL largo ayuda cuando habra lecturas futuras, no por si mismo.
/cost es mi factura de Claude?
No. /cost y los campos SDK son estimaciones utiles para monitoring. La prueba final es Claude Console, Usage and Cost API, invoice de proveedor, gateway records o la superficie de suscripcion activa.
Cuando puedo sospechar un bug de cache?
Cuando ya tienes same-route evidence: timestamp, version, model, route, MCP setup, permission changes, cache fields, turns comparables y billing surface. Antes de eso, un invalidator normal o TTL expiry es mas probable.