Anthropic prompt caching: cache the static top-level blocks, pick 5-minute or 1-hour TTL deliberately

TL;DR

Use it for conversational or bursty workloads where the same prefix repeats within minutes. Use it only for prefixes reused across a long session (long documents, persistent system instructions) where the 5-minute window keeps expiring.

Steps

1. Cache static, repeated content: tool definitions, the system parameter, few-shot examples, long reference documents. These belong before the breakpoint.
2. Do not try to cache the varying tail: the current user message, per-request data, anything with a timestamp. Only the stable prefix is eligible.
3. Cache the top-level block, not nested content. Anthropic's docs give citations as the example: citation content blocks themselves cannot be cached directly; cache the top-level document blocks that serve as the citation source material instead.
4. Default TTL is 5 minutes, refreshed at no cost on every use. Use it for conversational or bursty workloads where the same prefix repeats within minutes.
5. The 1-hour TTL ({"cache_control": {"type": "ephemeral", "ttl": "1h"}}) is priced at 2x the base input token price. Use it only for prefixes reused across a long session (long documents, persistent system instructions) where the 5-minute window keeps expiring.
6. Combining explicit breakpoints with automatic caching is supported: the automatic behavior handles the rest while your explicit breakpoints pin the sections you care about.
7. Failure modes this prevents: paying 2x for a 1-hour TTL on a prefix used twice; trying to cache nested citation blocks and getting no hits; caching per-request data that invalidates the prefix every call.

When to use

You are seeing this: Cache static, repeated content: tool definitions, the system parameter, few-shot examples, long reference documents. Use this skill when you run into "Anthropic prompt caching: cache the static top-level blocks, pick 5-minute or 1-hour TTL deliberately".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Anthropic's prompt-caching docs describe caching top-level blocks, the 5-minute default refreshed on use, the 1h TTL at 2x base input token price, and compatibility of automatic caching with explicit breakpoints. Verified live at https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching.