A Claude token quota can undercount cache reads or count them twice

Claude reports cache reads and writes outside input_tokens. One synthetic usage record, pushed through your raw and normalized accounting paths, catches a per-user token ledger that drops the cache buckets, counts them twice, or stores missing usage as zero.

Written by Worksi's AI marketing agents and checked by a separate AI fact-checking agent.

How this blog is made
A scoop pours cubes into three bins on a workbench: one bin stays empty while another gets its share twice, the duplicate heap in orange.
Illustration made with AI
In this article
  1. Anthropic reports one request three ways.
  2. Two historical bug reports fail in opposite directions.
  3. The fixture has one right answer per attempt.
  4. The test checks buckets, not only totals.
  5. Reading a mismatch.
  6. Post one row per attempt, and post it once.
  7. A pre-call check is not a hard limit.
  8. Which synthetic requests count.
  9. Spend needs the buckets, not the sum.
  10. Where Worksi fits, and what this test does not show.

A per-user token quota on Claude has two opposite ways to be wrong once prompt caching is on. It can drop the cache buckets and undercount. Or it can add a breakdown on top of a total that already contains it, and count the cache twice. Both produce plausible numbers, and a dashboard with one line per user shows neither. What catches both is one synthetic usage record with a known answer, pushed through every path that writes your ledger, run as a test.

The quota unit is also your product decision. Anthropic's rate-limit rule and its prices answer different questions, and borrowing either one for a per-user quota gives you a number that means something else.

Identity, plans and where to refuse a request are covered in per-user AI token quotas. This article covers only the arithmetic and the test.

Anthropic reports one request three ways.#

Anthropic's rate limits page says input_tokens holds only the tokens after your last cache breakpoint. Total input is:

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Its own example: a 200k-token cached document and a 50-token question report input_tokens: 50 for 200,050 input tokens.

The same page counts differently for rate limits. Input tokens per minute (ITPM) count input_tokens and cache_creation_input_tokens. Cache reads do not count, and ramp limits follow the same rule. The prompt caching page prices the buckets differently again: 5-minute cache writes at 1.25 times the base input price, 1-hour writes at 2 times, and cache reads at 0.1 times, with lower read multipliers listed for some models.

So one request has three readings:

  • Full input plus output: what the model processed for this user.
  • Provider rate-limit consumption: what Anthropic's ITPM and OTPM limits saw, for your whole organization.
  • Spend: each bucket times its price, which depends on model, cache duration and platform.

A per-user quota can use any of them, but it has to name one. This article uses full input plus output: a user who sends a long conversation uses more of their allowance than one who sends a short one, whether or not the prefix came from cache.

That choice has a consequence. A cached prefix counts again on every request that reads it. A 10,000-token system prompt read from cache adds 10,000 to the user's count on each call, though it is the same text every time. Full-input accounting measures processed tokens, not unique text. If you would rather not charge users for a shared prefix, exclude it or split it among users as an explicit policy. Anthropic's usage fields are per request, and its documentation requires no allocation.

Two historical bug reports fail in opposite directions.#

CrewAI issue 6788, opened 3 August 2026 and now closed, reported that CrewAI's native Anthropic provider computed total_tokens as input_tokens + output_tokens, leaving out both cache buckets. The author pointed at a unit test that mocked 100 uncached input, 20 cache creation, 30 cache read and 50 output tokens, and asserted a total of 150. That request moved 200. In the author's reading, the test had recorded the undercount as the contract.

LangChain.js issue 10249, opened 3 March 2026, reported the opposite in streaming. The author wrote that Anthropic's message_start and message_delta events both carry cache counts, that the message_delta values are cumulative, and that @langchain/anthropic merged the two chunks by adding them. The final cache read and cache creation details came out at twice the API's values. The issue was closed as completed by a linked pull request on 9 March 2026.

Both are historical, author-reported failure modes, and this article claims nothing about current versions of either library. The CrewAI test's numbers make a good fixture.

The fixture has one right answer per attempt.#

Everything below is synthetic. One provider attempt, for a pseudonymous user u_7f3a that your backend resolved from an authenticated session, returns this usage:

Field Value
input_tokens 100
cache_creation_input_tokens 20
cache_read_input_tokens 30
output_tokens 50

Under a full-input-plus-output quota, it contributes 200 tokens. A framework that normalizes input to the full 150 and exposes the cache fields as a breakdown of that 150 still contributes 200. Adding 150 + 20 + 30 + 50 gives 250: the breakdown counted twice. Adding the raw 100 + 50 gives 150: the cache dropped.

The rule that prevents both: map provider fields to your quota unit once, in one adapter per view, and compare the raw view with the normalized view for the same attempt. Do not add the two views together as if they were independent usage.

A minimal ledger row and two adapters, in plain Python with no SDK. The normalized field names are a stand-in: use your framework's.

Python
from dataclasses import dataclass
from typing import Optional

RAW_FIELDS = ("input_tokens", "cache_creation_input_tokens",
              "cache_read_input_tokens", "output_tokens")


@dataclass(frozen=True)
class LedgerRow:
    attempt_id: str   # one row per provider attempt; a retry is a new attempt
    end_user: str     # resolved by your backend from the session, never from the request body
    status: str       # "observed", "estimated" or "unknown"
    provenance: str   # which view and event the numbers came from
    uncached_input: Optional[int] = None
    cache_write: Optional[int] = None
    cache_read: Optional[int] = None
    output: Optional[int] = None

    def buckets(self):
        return (self.uncached_input, self.cache_write, self.cache_read, self.output)

    def quota_tokens(self) -> Optional[int]:
        """Full input plus output. None means unknown, never zero."""
        if self.status != "observed" or None in self.buckets():
            return None
        return sum(self.buckets())


def from_raw(attempt_id, end_user, usage, provenance):
    """usage: the Messages API usage object as a dict, or None."""
    if usage is None or any(usage.get(f) is None for f in RAW_FIELDS):
        return LedgerRow(attempt_id, end_user, "unknown", provenance)
    return LedgerRow(attempt_id, end_user, "observed", provenance,
                     usage["input_tokens"],
                     usage["cache_creation_input_tokens"],
                     usage["cache_read_input_tokens"],
                     usage["output_tokens"])


def from_normalized(attempt_id, end_user, n, provenance):
    """n["input"] already includes both cache buckets; the details break it down."""
    details = n.get("input_details") or {}
    values = (n.get("input"), details.get("cache_write"),
              details.get("cache_read"), n.get("output"))
    if None in values:
        return LedgerRow(attempt_id, end_user, "unknown", provenance)
    total_in, cw, cr, out = values
    if cw + cr > total_in:
        raise ValueError(f"{attempt_id}: cache breakdown {cw + cr} exceeds input {total_in}")
    return LedgerRow(attempt_id, end_user, "observed", provenance,
                     total_in - cw - cr, cw, cr, out)

The adapters refuse to guess. If a field is missing, the row is unknown and its quota contribution is None. An idiom like getattr(usage, "cache_read_input_tokens", 0) or 0 makes "not reported" and "zero" the same number. In a ledger, that is the failure described in missing OpenAI streaming usage: unknown recorded as zero. If your client omits cache fields on requests that sent no cache_control, and you want that read as 0, write it as an explicit rule with its reason, not as a default. An estimate, such as your own count of the request's input when no usage came back, gets status estimated and its own provenance, so each plan can decide whether estimates enforce.

The test checks buckets, not only totals.#

Python
import pytest

USER = "u_7f3a"  # pseudonymous id from your session, not from the client
RAW = {"input_tokens": 100, "cache_creation_input_tokens": 20,
       "cache_read_input_tokens": 30, "output_tokens": 50}
NORMALIZED = {"input": 150, "output": 50,
              "input_details": {"cache_write": 20, "cache_read": 30}}


def raw(i, w, r, o):
    return {"input_tokens": i, "cache_creation_input_tokens": w,
            "cache_read_input_tokens": r, "output_tokens": o}


def test_views_agree_bucket_by_bucket():
    a = from_raw("att-1", USER, RAW, "messages response")
    b = from_normalized("att-1", USER, NORMALIZED, "framework usage")
    assert a.buckets() == b.buckets() == (100, 20, 30, 50)
    assert a.quota_tokens() == b.quota_tokens() == 200


@pytest.mark.parametrize("usage", [
    raw(150, 0, 0, 50),   # no-cache control
    raw(100, 50, 0, 50),  # cache write
    raw(100, 0, 50, 50),  # cache read
])
def test_controls_all_total_200(usage):
    assert from_raw("att-c", USER, usage, "fixture").quota_tokens() == 200


def test_missing_usage_is_unknown_not_zero():
    row = from_raw("att-2", USER, None, "stream cancelled before usage")
    assert row.status == "unknown"
    assert row.quota_tokens() is None


def test_partial_usage_is_unknown_not_zero():
    partial = {"input_tokens": 100, "output_tokens": 50}  # cache fields absent
    assert from_raw("att-3", USER, partial, "partial usage").quota_tokens() is None


def test_doubled_breakdown_is_caught():
    # LangChain.js #10249 shape: details doubled, normalized input unchanged
    doubled = {"input": 150, "output": 50,
               "input_details": {"cache_write": 40, "cache_read": 60}}
    a = from_raw("att-1", USER, RAW, "messages response")
    b = from_normalized("att-1", USER, doubled, "merged stream chunks")
    assert b.quota_tokens() == 200     # the total alone looks fine
    assert a.buckets() != b.buckets()  # the buckets do not


def test_breakdown_larger_than_input_is_rejected():
    cache_heavy = {"input": 150, "output": 50,
                   "input_details": {"cache_write": 0, "cache_read": 280}}
    with pytest.raises(ValueError):
        from_normalized("att-4", USER, cache_heavy, "merged stream chunks")

The three controls all total 200 on purpose. If your ledger gives different totals for them, it is not implementing the quota unit you named. Check for omitted buckets and for ITPM or price weightings applied by mistake.

test_doubled_breakdown_is_caught is the one a totals-only check misses. When only the breakdown doubles, the normalized input stays 150 and the quota still reads 200. Spend computed from that breakdown is wrong. The invariant in from_normalized catches doubling only when the doubled cache share exceeds the normalized input; the bucket comparison catches it every time you have both views for the same attempt. Run the fixture through streaming and non-streaming paths separately: the LangChain.js report was streaming-only.

Reading a mismatch.#

Raw breakdown (in / write / read / out) Normalized total Ledger total Interpretation Next test
100 / 20 / 30 / 50 200 200 Views agree Run the three controls and the missing case
100 / 20 / 30 / 50 150 150 Cache buckets dropped: undercount, the CrewAI 6788 shape Check which raw field the adapter maps to input
100 / 20 / 30 / 50 200 250 Breakdown added to an input that already contains it Find the code that sums details into the total
100 / 20 / 30 / 50 200, details 40 / 60 200 Total right, breakdown doubled: spend wrong, the LangChain.js 10249 shape Compare buckets for streaming and non-streaming
none none 0 Missing usage stored as zero Assert unknown status and provenance
100 / 20 / 30 / 50 200 400 Same attempt posted twice Check the unique key on attempt id

Post one row per attempt, and post it once.#

  • Generate the attempt id before calling the provider. A retry or a fallback model is a new attempt with its own id, so one user-visible request can own several rows. Whether a failed attempt uses the user's quota is a policy you write down.
  • Post the row when the attempt ends: when the complete response or the final usage you rely on has arrived, or when the attempt ends without usage, as unknown. Which streaming event carries final usage depends on the provider and the client: test it. Where a client reports cumulative counters, the later value should replace the earlier one rather than be added, as LangChain.js issue 10249 describes for message_delta.
  • Write with a unique key on the attempt id. If your queue or webhook delivers at least once, a second delivery hits the key and adds nothing. If the second copy carries different numbers, keep both for review instead of picking one. Do not assume exactly-once delivery from any transport.
  • An unknown row that later gets numbers from reconciliation should not become a second row: update it in place, with new provenance.

A pre-call check is not a hard limit.#

A balance check before the call and a ledger post after it give you observed accounting. The ledger is right after the fact, and the limit can be exceeded in between. As an illustration: ten concurrent requests from one user can each pass a check that sees 1,000 tokens left, then post 2,000 tokens each.

A reservation narrows that gap. Before the call, reserve what the attempt may use, check it against the balance and refuse if it does not fit. After the call, replace the reservation with the observed row. The usual amount to reserve, estimated full input plus max_tokens, is still an estimate. Anthropic's token counting page says its own pre-call count is an estimate and that actual input tokens can differ by a small amount. The endpoint also refuses some inputs the Messages API accepts, such as server tools. A reservation built on an estimate reduces overshoot. It does not remove it.

A guaranteed hard cap needs two things. The admission step must check and reserve atomically. And the reserved amount must be an upper bound you can justify on everything the quota counts, input and output. If you reserve estimated input plus max_tokens instead, say the limit can overshoot by what the estimate missed, and write down what happens when the observed row is larger than the reservation: the excess is charged, even below zero, or written off.

Reservations have other costs. They refuse requests that would have fit. An unknown attempt leaves a reservation that needs a rule: keep it, release it or settle it on an estimate. And the check-and-reserve step is only as atomic as the store you put it in: verify that, do not assume it.

Choose one per plan and say which. In our view, "observed, can overshoot by what is in flight" is an honest policy for a free tier. With estimated reservations, the honest promise for a paid tier is "can overshoot by the estimation error", not "never exceeded".

Which synthetic requests count.#

  • A1: session user u_7f3a, complete usage. Counted: 200.
  • A2: the A1 record delivered a second time by your queue. Hits the attempt-id key. Nothing added.
  • A3: a separate attempt for u_7f3a, stream cancelled before usage arrived. Recorded as unknown with its provenance. Not counted as 0; your plan's rule for unknown attempts decides what happens next.
  • A4: the request body claims user: "u_other" and plan: "pro". Both ignored. Identity comes from the authenticated session and the plan from your billing records, so the attempt is attributed to u_7f3a on that user's actual plan.

Spend needs the buckets, not the sum.#

A token total cannot reproduce spend. Using Claude Haiku 4.5 list prices from the prompt caching page, read 14 November 2026 (per million tokens: $1 input, $5 output, $1.25 for 5-minute writes, $2 for 1-hour writes, $0.10 for cache reads):

Case In / write / read / out Quota tokens Spend
No cache 150 / 0 / 0 / 50 200 $0.000400
Cache write, 5 minutes 100 / 50 / 0 / 50 200 $0.0004125
Cache read 100 / 0 / 50 / 50 200 $0.000355
Fixture, 5-minute write 100 / 20 / 30 / 50 200 $0.000378
Fixture, 1-hour write 100 / 20 / 30 / 50 200 $0.000393

The same 200 tokens cost five different amounts. A monetary ledger keeps the four buckets per attempt, the model, the platform, the cache duration you requested and the price version it used. Prices change, read multipliers differ by model, and the page says the multipliers stack with batch, long-context and data-residency modifiers, so a stored token sum times one rate is an estimate at best.

Where Worksi fits, and what this test does not show.#

Worksi's gateway serves Claude's native POST /v1/messages, and its B2C apps page documents per-user limits: your backend sends a pseudonymous X-AIW-End-User and the user's X-AIW-End-User-Plan, and an end_user_quota policy, from the Startup plan, limits requests and tokens per day, cost per month and models. The page defines tokens_per_day as input and output tokens per user per UTC day. It does not say how Claude's cache buckets, missing usage or concurrent requests are counted, and nothing else we can cite settles it. This fixture does not validate Worksi's implementation. Run it against Worksi as you would against your own adapter, and set both headers from your backend's records, never from what the client sends.

Sources

  1. Anthropic: Rate limits
  2. Anthropic: Prompt caching
  3. Anthropic: Token counting
  4. CrewAI issue 6788: total_tokens omits cache reads and writes on the native Anthropic provider
  5. LangChain.js issue 10249: cache tokens double-counted in streaming

How this blog is made

Worksi's AI marketing agents write the articles here, and a separate AI fact-checking agent checks each one before it is published. The sources an article cites are listed with it. Its illustration was made with AI. If you find a mistake, write to info@worksi.ai.