API / SDK
Developer guides for the Claude API and SDKs — auth, streaming, tool use, cost control, and agent building, with working code and production-ready patterns.
43 Days Until Sonnet 4.5 Retires: I Counted Callers From the Usage CSV, Not From grep
claude-sonnet-4-5 retires on November 30. grep only shows what is written in code. Here is a single script that cross-checks model IDs in your code against the Console's Usage CSV, with the results from running it.
The Morning WS Came Back Empty in a Scheduled Task, and I Learned There Were Two Shells
Step 1 of a scheduled task left my workspace variable empty. The cause was a second shell. Here is what the same probe returned in both, and a tool_result guard that turns the silence into an error.
Sending 40 Rows From Make to the Claude API Stops at Row 14 — Avoiding the 429 With One Subtraction
Why a no-code automation that sends spreadsheet rows to the Claude API one by one hits a 429 partway through, and how to fix it. Seven spacing strategies tested on a mock bucket, a formula for the Sleep delay, and settings that stop failed rows from vanishing.
A 429 With retry-after: 120 Makes the Anthropic SDK Try to Wait 120 Seconds
I ran the Anthropic SDK's automatic retries against a mock server in 12 scenarios. Two retries by default, retry-after obeyed with no cap, and spend-limit 429s that no amount of waiting fixes. Code for a retry wrapper with a wait cap and a time budget, plus the logs.
Haiku 5.5 is cheaper per token, but your bill jumps fivefold past about 77k Haiku 4.5 tokens
On the price sheet, Haiku 5.5 costs roughly a tenth of Haiku 4.5. But the same text becomes about 30% more tokens, and a prompt over 100k tokens is billed at five times the rate. Here is the boundary in Haiku 4.5 terms, a script I actually ran, and the changes that return a 400.
Before Sonnet 4.5 retires, one script to find the arguments that will return a 400
claude-sonnet-4-5 retires on November 30. Swapping the model ID is not enough: budget_tokens, prefill, and tool_choice will fail. Here is a scanner built from the official migration guide, its real output, and the order I would fix things in.
Before You Switch Models, Replay Your Own Call Shapes Against the Candidate for a Few Tokens
Change a model ID and the first production request is where a 400 shows up. Here is a small replay script that checks your own call shapes against a candidate model with max_tokens 16 before you switch.
The Night Claude Returned 529, My Fallback Failed Too — Strip cache_control at the Provider Boundary
My Claude API fallback threw a TypeError because content blocks still carried cache_control when they reached another vendor. Here is the stripping function, the pre-send guard, and the weekly forced-fallback routine that finally made the fallback a real safety net.
Character counts won't predict PDF input tokens — bracket the cost per page before you send
How to estimate the input tokens of a PDF before sending it to the Claude API, by bracketing from page count rather than character count. Includes a measured 6.6x gap on a nine-page A4 document, the two separate increases that come with current models, and the count_tokens limitation that bites when you use file_id.
The morning a deprecation notice appeared, I checked versions before editing config
Claude Desktop and Cowork stop accepting older managed-configuration spellings on October 7. Here is how I sorted mine into what to fix now, what to fix after upgrading, and what changes meaning on its own.
I Send Images Twenty at a Time — The Day the 21st Image Changed the Rules for the Other 61
Sending 62 images in one request failed with invalid_request_error. The cause was the image count, not the payload size. Here is how I recounted visual tokens as 28px patches and built batches that respect count, dimensions, and payload at once.
The agent I built in the Console could not be adopted by ant apply
ant apply refuses some drift and silently duplicates other resources. Here is where that line sits, why claude-lock.json belongs in your commits, and the five doors a second copy walks through.
Writing 25 as your session budget caps it at twenty-five cents
Managed Agents session budgets are expressed in minor units as a string. Here is how I mixed up the unit, hit budget_reached in minutes, and what raising versus clearing a budget actually does.
A 75% cheaper cache read moved one bill by 29% and another by 2.8%
Fable 5.1 and Mythos 5.1 changed the cache read multiplier from 0.1 to 0.025. Here is how to estimate your own saving from your token mix, and how to fix code that hard-codes the multiplier.
The translation read perfectly and still crashed at runtime
When you translate app strings with the Claude API, the meaning can be right while the format specifiers quietly break. Here is a severity-aware acceptance check and a repair loop that only re-translates the broken lines.
Don't Hand Your Agent the Tool That Commits — Sorting Tools Into Advise, Prepare, and Commit
Before you wrap irreversible actions in an approval gate, decide which ones never belong in the tool list at all. A three-tier inventory, a rewritten tool definition, and a small script that flags commits hiding in your schema.
The 400 that rejects a thinking block, and finding the edit that caused it
On Claude Fable 5.1, editing the system prompt, tools, or earlier messages before a thinking block makes the request fail with a 400. Here is how to check whether your own agent loop does that in a single request, and how to move a rebuilt system prompt and client-side trimming to patterns that leave the prefix untouched.
Read the Catalog Your CLI Already Ships Before Bulk-Replacing Model IDs
A newer generation makes older model IDs look stale. Here is how to pull the catalog embedded in your installed binary, sort every reference into matched, date-mismatched, and malformed, and stop the replacement that would break working IDs.
The September Price Increase for Sonnet 5 Isn't Happening. Rebuilding a Forecast I Got Wrong in July
Sonnet 5's introductory $2/$10 pricing was supposed to rise to $3/$15 on September 1. It won't. Here's how to recompute your own effective cost from the usage numbers you already have, with working code.
The listen Stream Kept Reopening Against My Serverless MCP Server
No errors anywhere, yet connections to the MCP server kept piling up overnight. Here is what happens when a fixed platform timeout meets a resubscribe loop, reproduced in a few dozen lines.
The Connection That Dies Mid-Thought Is Being Killed by Your Relay, Not the Upstream
Put a proxy or Worker in front of Claude Code and long thinking pauses start dying. The cause is neither the model nor the upstream — it is your relay holding the byte stream. Six relay behaviors compared side by side, plus how to verify yours before it ships.
Move the Prompt Tools API Into Your Own Scripts Before Workbench Closes on August 17
The legacy Workbench and three experimental prompt endpoints shut down on August 17, 2026. Here is how to count what actually depends on them, plus working local replacements for templatize_prompt and improve_prompt with real output.
Swapping Tools Mid-Conversation Without Losing Your Prompt Cache
Tools can now be added and removed between turns, but the tool block sits at the very front of the cache prefix. I measured 12 mutation patterns with fingerprints and built a stable-core plus volatile-tail registry with a guard that refuses unsafe changes.
The 400-Character Preview That Was Still Holding On to a Megabyte
Truncating tool output in your own MCP server does not free the original. Node's sliced strings keep the parent alive. Here is the measured 13-character boundary, which flattening tricks actually work, and a heap-snapshot audit script that counts the retained parents for you.
The Line That Disappears at 100K: Measuring What Tool-Output Spill Actually Keeps
When agent tool output passes 100,000 characters, the full text spills to a file and the model sees only a head-truncated preview. Here are measured survival rates from a real repository, and the output envelope I built to push decision-relevant lines to the front.
Rebuilding a Remote MCP Server That Never Needed Mcp-Session-Id
The MCP spec release candidate drops the session header. Here is how I audited my own remote server for session coupling and moved it to signed cursors, with measurements.
One Shared Managed Agent Definition, Overridden Per Session
A design for collapsing four near-identical Managed Agents into one base definition, using agent version pinning and session-local overrides — with a validated factory and the traps I hit along the way.
When Memory Store Listings Returned Half the Rows: Migrating to agent-memory-2026-07-22
agent-memory-2026-07-22 changed memories.list: fixed ordering, stricter depth, segment-based path_prefix matching. How an audit quietly halved, an access layer that survives it, finding every call site with ast, and measured depth=1 traversal cost.
When Prompt Caching Was On but the Bill Didn't Move — Field Notes on Instrumenting cache_read to Close the Hit-Rate Gap
You added cache_control but your Claude API bill barely changed. Before guessing at fixes, record cache_read and cache_creation on every request and split the hit-rate gap into three causes: non-deterministic prefixes, TTL expiry, and sub-threshold blocks.
A Two-Stage Pre-Publish Gate for User-Facing AI Text in Consumer Apps
Design a two-stage pre-publish gate for short AI-generated text you ship to end users: a deterministic rule layer plus a Claude classifier, with fail-closed handling, generation-time vetting, and a cost model. Full implementation code included.
Precision Lives in the Second Stage: Reranking a Personal Knowledge Search with Claude
Embedding search alone leaves 'semantically close but not the answer' passages at the top. This is a two-stage design that gathers candidates broadly, then lets Claude reorder them by answerability, with structured scoring, abstention, and a cost estimate.
Coalescing Concurrent Claude API Calls: Single-Flight Against Duplicate Inference and Cache Stampede
A design for collapsing identical prompts that fire at the same instant into a single upstream Claude call, using single-flight (request coalescing). In-process and distributed implementations, jittered retries, and negative caching, with measured results.
Full-Size or Downscaled? A Per-Image Resolution Rule for Opus 4.7's High-Resolution Vision
Opus 4.7 finally read the fine texture in my wallpapers, so I sent everything at full size. My weekly image tokens jumped 2.4x. Here is the preflight that decides resolution and model per image, with the measured savings.
When Extended Thinking Flattened My Accuracy but Doubled the Bill — Field Notes on Measuring the Marginal Utility of Thinking Tokens
You pinned budget_tokens high 'to be safe,' accuracy barely moved, and the bill kept climbing. These field notes show how to ledger real thinking-token usage by p50/p95/hit-rate and measure how much accuracy each extra 1,000 thinking tokens actually buys.
Designing Around Claude API 413 request too large — Preflight Sizing and Splitting
Pack too much text, images, and tool_result into one request and Claude API rejects it with 413 request too large. Here is a code-backed design for measuring request bytes before you send, telling the two kinds of 413 apart, and splitting requests without breaking them.
When You Give an API Key an Expiration Date, Expiry Becomes a Plan Instead of an Accident
The Console now lets you set expiration dates on API keys. Here is how to fold planned expiry into unattended operations — with overlapping dual keys and a local expiry ledger — so your nightly jobs never go dark.
A Long Non-Streaming Response Was Billed Twice Past the 10-Minute Wall: Redesigning the SDK's Default Timeout and Retries
The Anthropic SDK's default 10-minute timeout and two automatic retries can silently re-run a long non-streaming response and bill you twice. Here is how the trap works, and how to close it with streaming, explicit timeout/max_retries, and a small local ledger — with measured before/after numbers.
Is This New Wallpaper Too Close to One We Already Ship? Near-Duplicate Detection with a Perceptual-Hash Pre-Filter and Claude Vision
A two-stage pipeline that catches the near-duplicates a SHA256 hash misses — recolored, lightly cropped, re-encoded — by pre-filtering with a perceptual hash and adjudicating only the close pairs with Claude Vision. With measured precision calibration and cost design from running a wallpaper catalog solo.
Tightening Tool Schemas From the Arguments You See in Production
Record the arguments Claude actually passes to your tools in production, then use that distribution to add enums and patterns back into your JSON Schema. With logging code and before/after numbers.
When Whisper Wrote 'Thanks for Watching' Into the Silence — Measuring and Killing Japanese Transcription Hallucinations
Whisper inserts phantom boilerplate into silent or noisy segments of Japanese audio. Here is how to measure hallucinations with no_speech_prob and avg_logprob, strip silence with VAD, and have Claude validate what remains — with the implementation and the routine that pulled it back.