Anthropic prompt caching minimums: below the per-model token floor your cache_control is silently ignored

TL;DR

These minimums apply on every platform where each model is available. Before adding caching to a short-prompt workload, measure the cached prefix length with the token-counting endpoint.

Steps

1. Know your model's floor. On the Claude API and on AWS, Google Cloud, and Microsoft Foundry, the minimum cacheable prompt length is:

   • 512 tokens: Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Fable 5, Claude Mythos 5
   • 1,024 tokens: Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4
   • 2,048 tokens: Claude Mythos Preview, Claude Opus 4.7, Claude Haiku 3.5
   • 4,096 tokens: Claude Opus 4.6, Claude Opus 4.5, Claude Haiku 4.5
2. These minimums apply on every platform where each model is available. Do not assume a shorter prompt caches on one platform and not another.
3. Requests to cache fewer tokens than the minimum are processed without caching and no error is returned. This is the failure mode: your code looks correct, the cache_control marker is present, and you get zero savings with no signal.
4. Before adding caching to a short-prompt workload, measure the cached prefix length with the token-counting endpoint. If you cannot clear the floor, skip caching entirely; the cache-write markup buys nothing.
5. When you change models, recheck the floor. A prompt that cached on Opus 5.5 at 512 tokens stops caching on Haiku 4.5 at the same length.
6. Failure modes this prevents: silent no-op caching on short prompts; assuming an error will tell you the prompt is too short; model swaps that quietly disable caching.

When to use

You are seeing this: Do not assume a shorter prompt caches on one platform and not another. Use this skill when you run into "Anthropic prompt caching minimums: below the per-model token floor your cache_control is silently ignored".

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 state the per-model minimums and that shorter prompts are processed without caching and no error. Verified live at https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching.