Claude API Versioning: Sonnet 4.6 to Sonnet 5

Dora here. I hit the problem in a model registry diff, not in the model response. One service had Claude Sonnet 4.6 pinned. Another used a shorter name. A third had the model name inside a prompt template because someone needed a quick fix on Friday. That is where Claude API versioning stops being documentation trivia and starts being a production risk.

This note is for backend, platform, and AI infra teams that already run Claude in real workflows. I’m using Sonnet 5 as a migration scenario, not as a license to guess future interface details. The useful work is the same either way: isolate model choice, test behavior drift, keep fallback capacity, and make the approval path boring. Boring is good here.

Why Claude Model Version Lock-In Happens

Model IDs, prompt behavior, tool schemas, and output drift

Version lock-in usually starts cleanly. A team pins a model, tunes prompts, ships a tool schema, builds dashboards, and moves on. Then the model becomes part of the application contract.

The first thing to separate is API version from the model version. Anthropic’s API versioning docs say requests need an anthropic-version header, such as 2023-06-01. That controls the API contract. It does not mean your model behavior is frozen forever.

The model string is a different contract. Anthropic’s model ID and versioning docs now make one point very clearly: every Claude model ID identifies a pinned model version. Starting with the Claude 4.6 generation, dateless IDs such as claude-sonnet-4-6 are still pinned snapshots. They are not evergreen aliases. Before 4.6, shorter Claude API aliases could point to the latest dated snapshot for that minor version.

I paused here, because this is exactly where teams get casual.

A pinned model ID keeps the underlying model stable, but it does not make the whole serving path immutable. Request routing, safety classifiers, sampling behavior, and platform-specific wrappers can still affect what you observe. Tool calls are even more sensitive. A small change in the instruction following can turn a required field into an optional-looking one. A slightly different refusal shape can break a parser that assumes every response has text.

That is why Claude API versioning should be treated as app governance, not a model-name cleanup task.

Build a Provider Abstraction Layer

Configuration-driven model selection and normalized responses

The model name should not live in route handlers, prompt templates, queue workers, or frontend flags. Put it in one configuration layer.

For most teams, the minimum useful structure is:

Layer	What it owns
Model registry	Approved model IDs, provider, platform, lifecycle state
Capability map	Vision, tool use, context limit, cache support, output limits
Request adapter	Provider-specific headers, model names, beta flags
Response normalizer	Text, tool calls, refusal states, usage, latency, model served
Routing policy	Primary model, fallback model, rollout cohort, rollback flag

The point is not abstraction for its own sake. It is making model routing inspectable. When a Sonnet 5 API migration is under review, the change should look like a config proposal, not a search-and-replace across the codebase.

If you run an LLM gateway, this is where it earns its keep. The gateway should log the requested model, resolved provider model, API version header, platform, cache behavior, stop reason, token usage, and fallback status. Without that record, every migration review becomes archaeology. Bad use of time.

One fewer switch. Sounds small. Adds up fast.

Cloud platforms need extra care. Anthropic’s model overview notes that Claude IDs and deployment names vary by platform. Bedrock and Google Cloud can also have lifecycle schedules that differ from the Claude API; Microsoft Foundry follows the Claude API lifecycle schedule but can use custom deployment names. A good registry stores these as separate provider targets. It does not pretend one model string works everywhere.

Maintain a Regression Eval Set

Golden tasks, edge cases, tool calls, and cost baselines

A model upgrade without evals is just optimism in deployment form.

I’d keep the eval set small enough that people actually run it. For a backend or AI infra team, that usually means four buckets.

Golden tasks are the normal money path: the requests that represent real users and real product value. Edge cases cover long inputs, ambiguous requests, malformed JSON pressure, policy-sensitive prompts, and prompts that historically caused weird output. Tool-call tests cover schema adherence, required arguments, parallel tool behavior, retries, and tool-result continuation. Cost baselines track input tokens, output tokens, cache reads, cache writes, latency, and stop reasons.

Anthropic’s migration guide is useful here because it frames migration as more than changing model. It points teams back to API behavior, tool use, token counting, pricing, and model-specific changes. That is the right mental model.

For a Sonnet-family migration, I would not start by asking “Is the new model better?” Too vague. I would ask:

Did the same tool call produce the same required fields?
Did the model stop earlier or later?
Did refusal handling change?
Did the token use move enough to change unit economics?
Did cached prefixes still hit?
Did output style drift in a way downstream code cares about?

If the eval set only checks final text quality, it misses the failures that wake people up.

Design Fallback and Rollback Paths

Failure routing, previous-model capacity, and circuit breakers

Fallback is not only for outages. It also covers behavioral failures.

There are two kinds of fallback to keep separate. One is request-level fallback: a specific call fails, refuses, times out, or returns an unusable tool shape, so the router tries another model. The other is release rollback: the rollout is producing bad aggregate signals, so traffic moves back to the previous approved model.

Anthropic’s refusals and fallback docs describe refusal responses and fallback patterns for Claude models that support that flow. Do not generalize any beta parameter across future models without checking current docs. The durable lesson is simpler: normalize refusals as a first-class response state, not as an exception bolted onto text generation.

Previous-model capacity is the part teams forget. If Claude Sonnet 4.6 is your rollback target during a migration, keep enough quota, provider access, prompt cache strategy, and monitoring coverage to serve real traffic. Not forever. Long enough to cover the rollout window, the first high-traffic cycle, and one business reporting cycle after migration. For many products that means weeks, not hours.

Circuit breakers should watch behavior, not just HTTP errors. Trigger rollback on rising invalid tool arguments, parsing failures, unexpected refusal rate, cost per successful task, latency breach, or human-review escalation. I don’t like rollback rules based on vibes. They are hard to defend in incident review.

Roll Out New Claude Models Safely

Shadow traffic, canaries, monitoring, and staged migration

A clean rollout starts before users see anything.

Shadow traffic first. Send copied production requests to the candidate model where policy and data handling allow it. Do not return the result. Compare outputs offline. For sensitive data, use sampled, redacted, or synthetic workloads instead. The point is to find obvious schema and safety drift before a user does.

Then canary. Start with low-risk routes, internal users, or a small percentage of production traffic. Keep the old model warm. Track model-level metrics beside product metrics. A model can look fine on latency and still fail because it changed a tool argument your billing worker depends on. Ask me how I know. Actually, don’t.

For prompt caching, treat a model change as a cache planning event. Anthropic’s prompt caching docs explain that cache hits require identical prompt prefixes, and the fallback-credit docs state that prompt caches are per-model. So existing prompt caches should not be assumed to survive a model-version change. Warm the new path separately and measure cache creation and cache reads after rollout.

The final step is staged migration. Move traffic by route, tenant, workspace, or job type. Keep migration records: who approved, what changed, which eval run passed, what dashboards were watched, and when rollback capacity can be removed.

This conclusion has an expiration date. Models update fast. The process should not.

FAQ

When should teams pin a Claude model identifier?

Pin a model identifier when the application depends on stable behavior: tool calls, legal review output, structured extraction, customer-facing answers, or cost-controlled batch work. This is an architecture governance decision, not only a code preference.

Use Anthropic’s current model ID rules as the source of truth. For 4.6-generation and later IDs, the dateless-looking model ID is still a pinned snapshot. For older models, shorter aliases may behave differently. Check the official docs before treating any alias as stable.

How long should previous-model fallback capacity be kept?

Keep previous-model fallback capacity through the full rollout window, the first normal peak-traffic period, and one reporting cycle where product owners can inspect quality and cost. The exact time depends on traffic shape.

If a workflow runs daily, a week may reveal enough. If it runs monthly, a few days tells you almost nothing. This FAQ is about retention duration, not rollback trigger design. Different question.

Can existing prompt caches survive a model-version change?

Do not assume that. Prompt caches depend on exact cached prefixes, platform rules, TTL, and model behavior. Anthropic also documents per-model cache behavior and model-specific cache billing. In practice, I treat a model migration as a cache miss until metrics prove otherwise.

For long system prompts or large tool definitions, pre-warm the new model path. Then watch cache creation tokens, cache read tokens, and time to first token separately.

Who should approve Claude model changes in production?

At minimum: the owning backend or platform lead, the product owner for affected workflows, and someone accountable for safety or compliance if the workflow touches regulated or sensitive content.

For an LLM gateway, approval should happen at the registry level. The pull request should show target model, source model, eval results, cost delta, fallback plan, rollout stages, and rollback owner. If those fields are missing, the change is not ready.

Conclusion

The mistake is treating model migration as a string replacement.

Claude API versioning is the control plane around model behavior: pinned identifiers, API headers, provider-specific model names, prompt cache behavior, tool schemas, refusal handling, eval baselines, and rollback capacity. A Sonnet 5 migration should go through that control plane the same way any serious production model change would.

The model may get better. The workflow still needs proof.

That’s all I can confirm. The rest you’ll need to verify against the official docs before rollout.

Previous posts: