Como funciona o prompt caching do Claude — e como não pagar de mais

Cache de prompt pode cortar o custo de chamadas repetidas de forma real — mas só se o prefixo cacheado for idêntico byte a byte entre requisições. Esta página explica onde colocar o breakpoint de cache, quando preferir RAG a contexto longo, e como tratar os erros que a API devolve.

Onde colocar o breakpoint de cache

Uma chamada à API é renderizada nesta ordem: tools, depois system, depois messages. Um breakpoint de cache no último bloco do system prompt cacheia o prefixo inteiro que veio antes dele — tools e system juntos — desde que esse prefixo seja idêntico byte a byte entre requisições.

O erro mais comum é colocar o breakpoint depois do conteúdo que varia por requisição: um texto de usuário único nunca se repete exatamente, então cada chamada grava uma entrada de cache nova, pagando um prêmio de escrita, e nunca lê um hit. Dados variáveis sempre por último, depois de qualquer coisa que se repete entre chamadas.

Um único byte muda e o cache inteiro invalida

Cache não é aproximado: qualquer diferença antes do breakpoint — um timestamp no system prompt, uma ordem de tools diferente — invalida tudo o que vem depois dele. Não existe cache parcialmente válido; ou o prefixo é idêntico e reaproveita, ou não é e reprocessa do zero.

Isso também decide a estratégia quando as chamadas não são contínuas: se o intervalo entre lotes de chamadas passa do TTL padrão do cache, mas ainda fica abaixo de uma hora, existe uma opção de TTL mais longo pensada exatamente para esse caso — a alternativa a simplesmente aceitar que o cache expira entre lotes.

429, 529 e 400 pedem reações diferentes

429 (limite de taxa) e 529 (sobrecarga) são erros transitórios: a resposta certa é repetir com backoff exponencial, porque o mesmo pedido tem boa chance de funcionar na próxima tentativa. Um 400, ao contrário, é bug na requisição — repetir sem corrigir nada só reproduz o mesmo erro indefinidamente.

Um pipeline que já lida com esses três também deveria ler os response headers de limite em toda chamada bem-sucedida, para fazer throttling proativo antes de bater no 429 — em vez de descobrir o limite só depois de já tê-lo estourado.

Quando contexto longo não é a resposta certa

Contexto longo funciona bem até o corpus crescer além de qualquer janela de contexto disponível — quando isso acontece, RAG escala de um jeito que simplesmente aumentar o contexto não escala. A troca tem um custo: RAG fragmenta o corpus em pedaços recuperáveis, o que funciona bem para busca pontual, mas atrapalha exatamente as perguntas que exigem síntese entre vários documentos ao mesmo tempo.

A decisão entre os dois não é sobre qual é "melhor" — é sobre o tamanho do corpus e o tipo de pergunta que o caso de uso realmente faz.

Compaction: por que o cliente ainda precisa cuidar do estado

Quando uma conversa longa ultrapassa a janela de contexto, o Claude Code pode compactar o histórico, resumindo trocas antigas para abrir espaço. Isso preserva a continuidade da conversa, mas não é automático do lado do cliente: a cada turno, continua sendo responsabilidade de quem constrói sobre a API reenviar corretamente o identificador da sessão e o histórico retornado — ou o estado se perde mesmo com compaction habilitado.

É o mesmo princípio de RAG versus contexto longo, visto de outro ângulo: gerenciar o que cabe na janela de contexto é uma responsabilidade contínua, não uma configuração que se liga uma vez e se esquece.