Desenvolvedores descobriram que o prompt caching do Claude pode falhar silenciosamente, cobrando taxas premium enquanto retorna zero tokens em cache. Uma execução de log de uma semana em um handler de WhatsApp não mostrou nenhuma leitura de cache, mas a API cobrou pelo recurso de cache — reduzindo os custos de US$ 1.890 para US$ 406 por mês.

Por que o problema é importante

O prompt caching tem o objetivo de reduzir custos e acelerar as respostas ao reutilizar uma parte estática de um prompt (o "prefixo"). Quando funciona, aplicativos de alto tráfego podem economizar centenas de dólares em suas faturas mensais. Quando não funciona, os desenvolvedores pagam por um recurso que nunca utilizam de fato, e a falha silenciosa não apresenta erro ou aviso para indicar o problema.

Como o bug se manifesta

A API aceita uma flag cache-control e um prefixo, e então informa quantos tokens foram lidos do cache. No caso observado, cada requisição retornou uma contagem de leitura de cache igual a zero. A chamada foi bem-sucedida, nenhuma exceção foi lançada e o faturamento refletiu o custo premium do cache. A falha é invisível, a menos que você registre explicitamente a contagem de leitura.

Formas comuns de o cache ser quebrado

  • O prefixo é muito curto – Cada modelo Claude define um comprimento mínimo de tokens para um prefixo que possa ser armazenado em cache. O Haiku 4.5 precisa de pelo menos 4.096 tokens; o Sonnet 4.6 precisa de apenas 1.024. Enviar um prefixo mais curto satisfaz o formato da requisição, mas o serviço ignora a instrução de cache.
  • Um byte volátil se move – O caching exige uma correspondência exata byte a byte. Adicionar um elemento dinâmico, como um timestamp, new Date(), ou o e-mail de um usuário no início do system prompt altera a sequência de bytes, fazendo com que cada requisição seja tratada como uma nova gravação sem cache.
  • A ordem da lista de ferramentas muda – As ferramentas são inseridas no início do prompt. Se o array de ferramentas for construído a partir de chaves de objetos, a ordem de iteração pode variar entre as chamadas, alterando o layout de bytes e quebrando o cache.

Correções que você pode aplicar hoje

  • Valide o comprimento do prefixo – Antes de enviar uma requisição, estime a contagem de tokens do prefixo em relação ao mínimo do modelo. Rejeite ou preencha o prefixo se ele for insuficiente.
  • Registre as leituras de cache em cada chamada – Registre o campo "cache read tokens". Uma sequência de zeros é um sinal claro de que o cache não está sendo utilizado.
  • Congele os bytes iniciais do prompt – Mantenha dados dinâmicos fora do segmento em cache. Se você precisar incluir informações específicas do usuário, coloque-as após o prefixo em cache.
  • Sincronize os identificadores do modelo – Certifique-se de que o ID do modelo usado no roteamento corresponde ao armazenado em sua tabela de cache; IDs incompatíveis impedem a busca no cache.

A questão do custo

Para um aplicativo que faz milhares de chamadas diariamente, passar de sem cache para com cache pode reduzir drasticamente as despesas mensais — de aproximadamente US$ 1.890 para US$ 406 no caso relatado. Mesmo um tráfego modesto apresenta economias perceptíveis, e o ganho de desempenho ao reutilizar um prompt estático grande pode reduzir a latência.

Contraponto

No entanto, a natureza silenciosa da falha significa que a única maneira de ter certeza de que você não está pagando a mais é verificar a contagem de leitura — algo que muitos negligenciam.

O que observar a seguir

  • Dashboards de métricas – Adicione um medidor para tokens de leitura de cache ao lado do volume de requisições.
  • Estabilidade na ordenação de ferramentas – Se você depende de listas de ferramentas geradas dinamicamente, considere ordená-las de forma determinística antes de incorporá-las ao prompt.

Resumo: O prompt caching do Claude não gera um erro quando ignora silenciosamente sua requisição. Verifique a eficácia do cache registrando os tokens de leitura, force um comprimento de prefixo adequado e mantenha os bytes iniciais do prompt imutáveis. Somente assim você colherá os benefícios prometidos de custo e velocidade.