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.
Don't Trust the Confidence Score: Per-Class Calibration and Abstain Routing for Vision Classification
Overall accuracy looked fine while individual categories quietly collapsed. Here is how I calibrated Claude Vision's self-reported confidence per class and routed abstentions to a human queue.
My Nightly Batch Was Quietly Running on a Bigger Model — Declaring Per-Task Model Ceilings and Enforcing Them
Scatter model names through your code and a cheap batch job will eventually run on an expensive model. Here is a manifest that declares a ceiling per task, a deny-by-default resolver, and a morning audit that catches drift — with working code.
Same Output, Different Path — Guarding Agent Trajectories with Invariants
When the default model changes, your final output can stay correct while the path your agent takes quietly shifts. Here is a trajectory regression harness built on recorded tool traces and deterministic invariants, with working code and measured numbers.
When the RAG Started Being Confidently Wrong — Field Notes on Measuring Retrieval Misses With Groundedness
In a Claude API RAG, the answers stay fluent while the facts drift. Often the cause is a silent recall decay on the retrieval side, missing the document that holds the answer. Field notes on measuring groundedness and retrieval hit rate and walking the system back, with working code and real numbers.
The 200K-Token Cliff That Doubled My Nightly Bill — A count_tokens Preflight to Avoid Long-Context Pricing
Sonnet 5's native 1M context switches the entire request to long-context pricing the moment input crosses 200K tokens. Here's how I caught that silent cost cliff before sending, using the billing-exempt count_tokens API, with working Python and TypeScript code.
Rolling Out Agent Behavior Changes Gradually with Feature Flags
When an unattended agent changes its prompt or behavior all at once, quiet regressions hide until morning. Here is a design for assigning new behavior to only a fraction of runs, keeping a control group, and adding deterministic bucketing, canary comparison, and automatic rollback.
Contract-Test Every Tool Before You Submit or Automate an MCP Connector
A connector that works once in a chat can still break silently in an unattended job through misread response shapes or double-fired writes. Here is a small harness that machine-checks tool descriptions, response contracts, idempotency, and latency, with measured numbers.
Four sites, one Claude bill: attributing spend per workspace to decide which pipeline to trim
When several projects share one Claude organization, the bill arrives as a single number that hides which pipeline is expensive. Field notes on splitting that spend per workspace with the Cost and Usage Report group_by, defensively parsing the results, and deciding what to trim by cost-effectiveness.
When Claude API Suddenly Starts Returning 429 in Production — Field Notes on Measuring Rate-Limit Headroom from Headers and Throttling Before You Run Dry
Scrambling to add retries after a 429 is always a step behind. Claude API writes how much you have left into every response header. These are field notes on measuring that headroom continuously and throttling yourself before it runs out.
Fable 5 Is Back Worldwide and Sonnet 5 Is the Default — Where Each of the Three Models Belongs in a Solo Automation Stack
With Fable 5 redeployed worldwide and Sonnet 5 now the default, solo automation suddenly has three capable top-tier models to reach for. Instead of ranking them, this piece assigns each a role and captures that in a policy object with a fallback ladder and run-level logging.
Don't Let the Opus 4.7 Fast Mode Retirement (July 24) Kill Your Unattended Jobs
claude-opus-4-7 fast mode retires on 2026-07-24, and speed: fast starts throwing errors. Here's how to keep unattended pipelines from breaking silently: mechanically detect where fast mode is used, add a fail-closed runtime guard, and migrate to 4.8 with working code.
Reading the Claude apps gateway Announcement, I Rebuilt My Indie-Scale Control Plane
The self-hosted Claude apps gateway is a control-plane/data-plane separation you can scale down. Per-app cost attribution, model allowlists, and fail-closed spend caps, implemented as a small Cloudflare Workers proxy.
claude-opus-4-7 Fast Mode Retires on 7/24 — Guard It at the Capability-Pair Level
Opus 4.7 fast mode is being retired on 2026-07-24. The model ID stays valid while only the speed parameter starts failing, so model-ID audits miss it. Here's a capability-pair preflight with automatic migration.
How Many Concurrent Claude API Requests Can You Actually Hold? Sizing Production Infrastructure with Little's Law and Measured Memory
Concurrency, queue depth, and memory are numbers you can derive, not guess. A working method for sizing Claude API production deployments with Little's Law, a memory probe, and a 30-minute load check — learned the hard way from an OOM crash.
A 40% Lower Price Doesn't Mean a 40% Lower Bill — Measuring the Opus 4.8 to Sonnet 5 Migration by Cost per Completed Task
Sonnet 5's intro pricing looks ~40% cheaper than Opus 4.8, yet extra tool turns can flip the math. Working TypeScript for consumption vectors, a paired-run harness, and break-even turn counts.
Introductory Pricing Has an End Date — Effective-Dated Cost Forecasts for the Sonnet 5 Price Step
Claude Sonnet 5's introductory $2/$10 pricing ends on 2026-08-31 and reverts to $3/$15. A static price map will quietly understate your September forecast by a third. Here is an effective-dated price table and forecast design that absorbs the step.
When 41 of 20,000 Message Batches Requests Quietly Vanished — Field Notes on Reconciling and Requeuing Partial Failures
processing_status: ended does not mean every request succeeded. How errored and expired results hide inside a finished batch, and how a custom_id ledger catches every gap and requeues safely — with real cost and timing numbers.
Your Cache Hit Rate Resets to Zero the Morning You Switch Models — Prompt Cache Rewarm Design for the Opus 4.8 to Sonnet 5 Cutover
Prompt caches are scoped per model, so day one of a model migration starts at a 0% hit rate. Why percentage-based rollouts break cache economics twice over, and how cohort cutover by task family preserves them — with working measurement code.
When the Model Survives but One Parameter Expires: A Dated Deprecation Calendar for Claude API Requests
Your model ID can stay valid while a parameter you pinned quietly reaches its sunset date and takes the batch down with it. Here is a design that breaks a request into parts, gives each part its own expiry date, and catches the problem before the call goes out — with working TypeScript and real operational numbers.
When Claude API Document Extraction Is Confidently Wrong — Field Notes on Catching Silent Errors with Invariants
In structured extraction from invoices and contracts, the real danger isn't a crash — it's a value that's silently wrong while the schema validates and confidence reads high. Field notes on invariants, two-pass extraction, and tracking field-level error rates.
A Fail-Closed Model Pricing Registry So New Models Don't Quietly Break Your Cost Math
When Opus 4.8 and Haiku 4.5 landed in the Messages API, rates scattered across my code silently skewed the cost rollup. Here is how to centralize per-model rates and fail closed on unknown models, with complete working code.
The Same 429 Wears a Different Face on Each Route: Running Claude Safely over Anthropic Direct and Azure Foundry
With Claude now generally available on Microsoft Foundry, a two-route setup is realistic even for solo developers. Here is how to fold the route-by-route differences in 429s and retry-after into one normalized error type and a single backoff policy.
When a Tool Result Is Too Big and Melts Your Context Window: Designing Cursor-Based Pagination
When a list tool returns hundreds of rows at once, an agent's context can collapse in a single call. Here is a cursor-based pagination design that keeps tool output small and protects your token budget, with working code.
Stop rebuilding intermediate files every request: reuse the Code Execution container to carry pipeline state
How to reuse the Code Execution container across requests by passing its container ID, so generated files and intermediate results carry over to the next step. Includes the execution-time billing trap and how to handle container_expired safely, with working code.
Let Claude Actually See the Images Your Tools Return — Use Image Blocks in tool_result and Cut Tokens by Roughly 10x
Stuffing a base64 string into a tool_result makes the same image cost roughly 10–20x more tokens. Here is how to return it as an image content block instead, with SDK code, a token-cost estimate, and the gotchas I hit in production.
When Context Editing Made My Agent Re-run the Same Search — Field Notes on Clear Boundaries and Cache Invalidation
After turning on Context Editing to auto-clear tool results, the agent forgot what it had just read, re-ran the same tool, and the cache rebuilt every turn so costs went up. Field notes on instrumenting the silent regression and setting trigger, keep, and clear_at_least from measured data.
Did That Post Actually Go Through? Safely Retrying an Interrupted MCP Write Without Double-Executing
When an MCP write tool call is interrupted by a dropped connection, you can't tell whether the server ran it. Here's why naive retries cause double-execution, and a working wrapper that uses idempotency keys and a reconcile read to retry safely — with examples from an unattended pipeline.
Measure Streaming CPU and Dropped Chunks to Stabilize Long Batch Jobs
You start an overnight batch, and by morning only half of it finished. The culprits were CPU pinned during streaming and a quiet connection drop. Here is a monitor wrapper that measures stream CPU and throughput, and resumes from interruptions.
Every Tool Call Succeeds, Yet Nothing Moves Forward: Detecting Stagnation in Unattended Agents
No errors, yet the agent keeps replaying the same move while your budget quietly drains. Here is how to detect a success-but-no-progress loop using a progress oracle and action fingerprints, with a working Python implementation that halts safely.
A Silent Drop to a Weaker Model Is Scarier Than an Error: Designing a Capability Floor for Claude API Fallback
When a model becomes unavailable in an unattended pipeline, automatically dropping to a weaker model is dangerous. Drawing on years of running automated indie pipelines, this is how to use per-task capability contracts and a degradation budget to decide where to stop.
Designing the Give-Up Condition in Self-Repair Loops: Four Error Classes, Four Retry Budgets
LLM self-repair loops break on the fantasy that 'if you keep fixing, it eventually passes.' Classify errors into four classes, give each its own retry budget. Working TypeScript and real cost numbers included.
When Claude API Streaming Stops Without an Error: Detecting Silent Stalls and Resuming Mid-Stream
How to catch the 'silent stall' where Claude API streaming stops with no exception at all, using a content-level watchdog that times the gap between tokens, plus a resume path that carries received text forward as an assistant prefill, and a four-layer timeout budget for long-running automation.
Stop the Bill Before It Balloons: Designing API Key Blast Radius for Unattended Pipelines
Designing for leaks instead of pretending they won't happen: workspace-scoped keys, zero-downtime rotation, and a usage watchdog that flags spikes with a rolling baseline and median absolute deviation — wired into a scheduled run.
When the Same Model Name Starts Behaving Differently: A Startup Canary for Unattended Pipelines
An in-place Opus upgrade can change your output, and an unattended publishing pipeline will never notice. Here is a lightweight startup canary that fingerprints behavior, catches drift, and halts the batch — with measured cost and latency.
Generating localized App Store listing metadata within character limits using the Claude API
Raw translations overflow App Store Connect's character limits. Generate per-locale listing metadata within them using Claude API structured output and a repair loop.
Reach a Remote MCP Server in a Single API Request: Implementing the Messages API MCP Connector
How to call a remote MCP server's tools using only the Messages API's mcp_servers and mcp_toolset—no local MCP client. Covers allowlist/denylist design, response handling, and the pitfalls to avoid before unattended production use.
When the Previous Run Hasn't Finished and the Next One Starts: Leases and Fencing Tokens for Scheduled Agents
A scheduled agent that runs on a fixed clock can overtake itself and start twice. From the moment a naive lock breaks to leases, fencing tokens, and bounded catch-up — worked through with the implementation I actually run.
When Your Support AI Is Confidently Wrong in Production — Notes on Refusing Outside Its Grounding and Routing to Humans
A field-tested approach to the Claude API support agent that demos perfectly yet states non-existent facts in production. Covers deciding 'don't answer' at retrieval time, grounded generation, measuring confident-wrong rate, and tuning escalation precision.
I Edited One Line of a Tool Description and the Whole Prompt Cache Rebuilt — Where to Place cache_control Breakpoints
Hit rate suddenly flatlined at zero because a volatile block sat upstream of stable ones. This walks through how prefix-cache cascade invalidation works, how to reorder blocks from stable to volatile, and where to spend your four cache_control breakpoints — with code and decision tables.
What I Decided the Day the Ceiling Doubled: A Headroom Budget for Scheduled Jobs on One Shared API Key
Why I did not compress my intervals when the rate limit doubled, and how to design a headroom budget for running several scheduled jobs on one shared API key, with measurement and working code.