[DOCS] Clarify "Worst-Case" cost estimation in Token Counting API regarding Prompt Caching

Documentation Type

Unclear/confusing documentation

Documentation Location

URL: https://platform.claude.com/docs/en/build-with-claude/token-counting

Section/Topic

The "FAQ" section, specifically the question: "Does token counting use prompt caching?"

Current Documentation

Does token counting use prompt caching? No, token counting provides an estimate without using caching logic. While you may provide cache_control blocks in your token counting request, prompt caching only occurs during actual message creation.

What's Wrong or Missing?

The documentation introduces the Token Counting API as a tool to "manage costs and rate limits." However, since the API ignores caching logic, the input_tokens returned represents a "worst-case" scenario (100% uncached).

Because cache hits are billed at 10% of the base price ($0.1x), a developer using this API to estimate costs for a RAG application or a long-running agent might overestimate their actual billable costs by up to 90%. Furthermore, since cached tokens do not count toward ITPM (Input Tokens Per Minute) rate limits on most models, relying on this API for rate-limit management will lead to significantly throttled request routing that doesn't reflect actual capacity.

Suggested Improvement

Add a warning/note block in the FAQ section to clarify the implications for cost and rate-limit logic.

Suggested Text:

Note on Cost and Rate Limit Estimation: Because the Token Counting API does not calculate cache hits, the input_tokens value reflects the maximum possible uncached count. If your workflow relies on Prompt Caching: 1. Cost Estimation: Actual costs may be up to 90% lower than the estimate (as cache hits cost 0.1x). 2. Rate Limits: Since cached tokens do not count toward ITPM limits for most models, the Token Counting API will provide an overly conservative view of your remaining rate limit capacity. Developers should implement their own logic to subtract known cached prefixes from the result returned by this API to get a realistic "Net New" token count.

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation: Prompt Caching Pricing, Rate Limits - Cache-aware ITPM.
• Context: In high-volume agentic workflows (like Claude Code), the difference between a 200k token "estimate" and a 20k token "actual" (after 180k cache hit) is the difference between a request being rejected by a local orchestrator or accepted. Clearer guidance helps developers build better local middleware.