Why Headroom Breaks on AWS Bedrock — and How to Fix All Four Failures

Why you're on Bedrock — and why the bill climbs

Compliance keeps regulated teams on Bedrock so data never leaves AWS — and agentic workflows multiply tokens, because one user question fans out into ten times the tokens through the agent's internal loops.

If you're a platform or ML-infra engineer at a fintech or a health company, you probably didn't choose Amazon Bedrock for its ergonomics. You chose it because your security review said inference has to run inside your AWS account, against data that never crosses a third-party boundary. Bedrock delivers exactly that — and then the bill starts climbing in a way that direct API users never see.

The reason is the agent loop. A single user prompt doesn't map to a single model call. A tool-using agent reads a tool result, reasons about it, calls another tool, re-reads its own growing history, and repeats — so one question can drive on the order of ten times the tokens of a naive single-shot call. Every one of those internal turns re-sends the accumulated context. On a per-token biller like Bedrock, that compounds fast, and tool-heavy runs are where the surprise invoices come from. Independent write-ups of Bedrock economics put the "hidden" overhead well above the headline per-token rate once you account for agent multipliers and repeated context — see TrueFoundry's pricing breakdown. Treat those figures as their estimates, not ours.

The four ways it breaks on Bedrock

Stock Headroom on the Bedrock agentic path fails four distinct ways — a 404 on native routes, a broken SigV4 signature, a prompt cache that reports frozen but saves nothing, and a botocore crash on temporary credentials — and throws five distinct error strings. Each maps to an open upstream issue.

Failure 1 — 404 on Bedrock-native routes

Claude Code in Bedrock mode talks to native paths — /model/{id}/invoke, /invoke-with-response-stream, and GET /inference-profiles. The stock proxy only knows the Anthropic-style /v1/messages shape, so those requests come back 404. Worse, Claude Code's auto-mode classifier probes /inference-profiles to decide how to route; a 404 there makes it fail closed, so the agent degrades instead of erroring loudly. This is tracked upstream in issue #1589.

Failure 2 — InvalidSignatureException

This is the one that stops people cold. Bedrock authenticates with SigV4, and SigV4 signs a hash of the request body. Headroom's whole job is to rewrite that body — it compresses it. So the body the proxy sends no longer matches the body that was signed, and Bedrock rejects it:

botocore.exceptions.ClientError: An error occurred (InvalidSignatureException):
The request signature we calculated does not match the signature you provided.

A related trap: in Bedrock mode, some clients ignore ANTHROPIC_BASE_URL entirely and sign for the real Bedrock endpoint, so even a correctly-running proxy is bypassed or mis-signed. The fix is to re-sign the request with SigV4 after compression, on the proxy's way out — which is exactly what our upstream PR #1220 does (auto-detect CLAUDE_CODE_USE_BEDROCK and re-sign).

Failure 3 — the cache reports frozen but saves savings_pct: 0.0

This is the most expensive failure because it's invisible. In --mode cache, Headroom freezes the prefix and prints prefix_frozen — so it looks like caching is on. But on Bedrock it never injects the cachePoint block that the Converse API actually needs, so no cache checkpoint is created and the report reads savings_pct: 0.0. The cache is silently dead (issue #1345; the fix that preserves the cache_control blocks through LiteLLM's message conversion is #1390).

And once you do start injecting markers, Bedrock has a hard ceiling that catches naive stacking. Claude models allow at most four cache checkpoints per request, processed in the order tools → system → messages. Put one on tools, one on system, and two on messages and add a fifth, and Bedrock returns:

ValidationException: A maximum of 4 blocks with cache_control may be provided. Found 5.

Failure 4 — ModuleNotFoundError: botocore on STS credentials

Regulated environments rarely hand out static AWS keys — they use temporary STS credentials with a session token, from an assumed role or an SSO login. The stock proxy image doesn't bundle botocore, so the code path that handles the session token crashes on import:

ModuleNotFoundError: No module named 'botocore'

It works on a laptop with static keys and dies the moment it hits the environment that actually needs it — a production account on assumed-role credentials (issue #1551).

The savings math (a formula, not a promise)

Savings stack multiplicatively: compression shrinks the input, and caching prices the repeated prefix at 0.1× on reads. The bill in token-equivalents is input + 1.25× write + 0.1× read.

No magic percentages — here's the model. Bedrock reports three usage numbers, and you pay for a weighted sum of them: uncached input at 1×, cache writes at 1.25× (the price of putting something in the cache with a 5-minute TTL), and cache reads at 0.1×. So the effective bill for a request is:

Caching attacks the read term — a repeated prefix that would cost 1× every turn costs 0.1× instead. Compression attacks the input term — fewer tokens to send in the first place. They compound: compress the input, then cache what's stable inside it. On a realistic 6-turn agentic session (compact JSON tool-results, a 100-service fleet context), measured on Claude Sonnet 4.5 in us-east-1:

Caching alone — just making the dead cache actually work — took the session from 619,865 to 257,250 token-equivalents, a 58.5% cut. Layering compression on top brought it to 183,672 — 70.4% off the unoptimized bill. That last step is compression cutting the already-cached total by a further 28.6% — the two levers stack because they attack different terms.

These are our measured numbers on a synthetic-but-realistic workload. Production numbers on a live regulated-fintech workload are being measured now, and will be published when they're real rather than modeled.