A request that had worked unchanged for three years started returning 400. The body was identical. The model was identical. The field the API objected to was temperature, set to the value that had been its documented default since 2023 — a number nobody on the team had ever chosen, tuned, or thought about. Nothing in the application had changed that week. What had changed was a dependency.
On 21 October the Claude API got its first new version since 2023-06-01. If you call it over plain HTTP, you opt in by sending anthropic-version: 2026-10-21, and you opt in on purpose. If you call it through an SDK, you do not opt in at all. An SDK's requests use the API version that was current when that SDK's major version was released, so the first majors to carry the new contract — anthropic 2.0.0 in Python, @anthropic-ai/sdk 1.0.0 in TypeScript, Go v2, Java 3.0.0, Ruby 2.0.0, PHP 1.0.0, C# 13.0.0, and version 2.0.0 of the ant CLI — select it for you the moment they install.
The migration guide for this is genuinely good. It is explicit about every change, in every language, with before-and-after for each one. None of what follows is a complaint about the change. It is a complaint about us, and about the way almost every team we audit handles dependency upgrades: a major version bump arrives as maintenance, gets reviewed as maintenance, and carries an API contract change through a pipeline that has no place to put one.
A parameter is now wrong at its old default
Under 2026-10-21, a request that sends temperature, top_p, or top_k returns a 400 — even at the parameter's default value. There is no deprecation window where the field is ignored. It is rejected.
That last clause is what makes it expensive. A deprecation you can grep for. A field that is only wrong when it holds an unusual value, you can reason about. But a field that fails at the value it has always had defeats the instinct every reviewer has, which is to scan for the odd number and move on. Every call site that sets the parameter breaks, including the ones that set it to the number the API itself used to pick.
The change also applies to token counting and to each request inside a Message Batch created under the new version. The batch case is the one that bites in production: a batch submitted at deploy time can surface its failures hours later, long after the deploy window closed and the dashboard went green.
- The shared wrapper. — most teams have one
callModel()that sets sampling parameters once, years ago, because an example did. One line, one grep, easy. This is the case everyone finds. - The config row.— a per-tenant or per-feature table with a
temperaturecolumn, read at request time and spread into the params object. Grep finds the spread. It does not find the thousand rows that make it non-empty. - The serialised prompt object.— prompt definitions stored as JSON in a database or a CMS, carrying their sampling settings with them. These were written by people who have since left, and they are not in the repository at all.
- The evaluation harness.— which almost always sweeps temperature on purpose, and which almost nobody runs in CI on a dependency PR.
The version lives in your lockfile, not your code
Open the pull request your bot raised. It changes a version range and a lockfile. There is no line in it that names an API contract, because the contract is not expressed anywhere in your source. It is implied by a number in a manifest, resolved by a package manager, and only becomes visible in the headers of a request in production.
This is why the usual review signals are useless here. The diff is small, so it reads as low risk. The tests pass, because the tests mock the client. The type checker is quiet, because most of what changed type-checks fine. Every heuristic a reviewer has points the same wrong way.
“The request your code describes and the request your process actually sends stopped being the same thing the day a version number moved into a lockfile.”
It also means the upgrade is not a property of the repository. It is a property of each call path. On Amazon Bedrock, 2026-10-21 is available only for Claude 4.7 and later models — so a service still pinned to a 4.6-or-lower model on Bedrock has to stay on the SDK version it uses today, and has to switch models before it can move. One pinned model in one background job is enough to make a repo-wide bump the wrong unit of work.
Two copies of the SDK, one process
The companion cloud packages are versioned against the core SDK. In TypeScript, v1 of @anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk and @anthropic-ai/google-cloud-sdk each require v1 of @anthropic-ai/sdk, and their earlier releases require something below 1. Upgrade one and not the other and nothing errors. Your package manager does exactly what it is designed to do: it satisfies both constraints by installing a second, older copy of the SDK alongside the new one.
Now half your traffic is on 2023-06-01 and half is on 2026-10-21, inside the same deploy, with no flag or config anywhere that says so. The 400s that result are intermittent and correlate with nothing an engineer can see, which is how a configuration problem gets escalated as a provider problem. The C# packages behave similarly — an earlier companion version installs next to Anthropic 13.0.0 without complaint and can fail when it runs.
Not the dependency list — the resolved tree. npm ls @anthropic-ai/sdk printing two entries is the whole bug, and it is the one check that takes ten seconds and is almost never in anyone’s upgrade routine. Make a duplicate a CI failure and the class of problem stops existing.

The key moved headers, and the API does not mind
The new SDK and CLI majors send your API key as Authorization: Bearer <key> instead of in the X-Api-Key header. The Claude API accepts a key in either header, so the provider side of this is a non-event. That is precisely the problem: the endpoint keeps answering, which removes the one signal that would have told you something moved.
Everything on your side that reads the old header is now reading a header that is not there. The documentation calls out proxies and gateways, and those at least fail loudly — a gateway that authenticates on X-Api-Key starts rejecting its own traffic, and you find out in the first minute. The quiet ones are worse.
Things in your own stack that read the auth header
- Log redaction rules keyed to
X-Api-Key, which now pass theAuthorizationheader through untouched - Per-tenant routing middleware that picks a backend by inspecting the key prefix
- Test stubs and contract fixtures that assert on the old header and therefore still pass locally while production has moved
- Anything that deliberately removed
X-Api-Keyso a request would send only a bearer token — that code now strips nothing
The redaction one deserves its own paragraph, because it is a security finding dressed as a formatting change. A rule that masks X-Api-Key stops matching, and the credential is now in a header your filter has never heard of. No exception, no failed request, no alert. You discover it by searching your log store for the key prefix, which is not a thing anyone does on a Tuesday.
There is a second change layered on this: a client now holds one credential. Earlier versions sent both an API key and an authentication token when they had both, each in its own header. If your architecture was a token for the gateway and a key for the API behind it, that shape no longer happens by default — and when both environment variables are set, the client picks ANTHROPIC_API_KEY and logs a warning exactly once per process. Once per process, on a web server, is a line nobody will ever see.
The changes that never raise anything
Catalogue the breaking changes of any major and you find two groups. The ones that throw, which cost you an afternoon. And the ones that return success with something missing, which cost you a quarter. This upgrade has a clean example of the second kind in almost every language.
Start with the one that is not even in the application. A Go module at major version 2 or later must carry the major in its path, so the install command your CI has run for two years — the one ending in /cmd/ant@latest — keeps installing the newest v1 release, with no error and no warning. The word latest quietly stops meaning latest. Your pipeline is now pinned to the previous contract by a path, and the only symptom is that nothing changed.
Then the one inside the request. The non-beta Models methods no longer accept betas. In the statically typed SDKs that is a compile error and you fix it in minutes. In the dynamically typed ones, passing it does not raise — it simply no longer sets the anthropic-beta header. A feature flag you believe you are sending stops being sent, every call succeeds, and the behaviour you were relying on silently reverts to the default.
“The dangerous half of a migration is never the half that throws. It is the half that keeps returning 200 with one header missing.”
Two more are worth naming because they come from code that is usually correct. A document block placed directly in an assistant message now returns 400, and so does a text block carrying a non-empty citations array in a user message. Both were accepted before. Both are exactly what a conversation-replay path produces when it echoes prior turns back verbatim — which is to say they break on long sessions and old threads, not on the happy-path request your smoke test sends.

What goes on the update PR now
We stopped treating provider SDKs as ordinary dependencies. They are the only packages in most of our projects where the installed version selects a remote contract, so they get their own review path. Five things, none of them expensive.
- 1Assert the version header in a test.— one test that captures an outgoing request and checks the
anthropic-versionit carries. It is six lines, it never changes, and it fails the instant a bump moves the contract. That single test would have caught every item in this post before the branch merged. - 2Replay production-shaped payloads.— fixtures captured from real traffic, including the requests assembled from config rows and stored prompt objects. Hand-written fixtures only ever test the parameters you remembered you were sending.
- 3Fail CI on a duplicated SDK.— resolve the tree, not the manifest, and treat a second copy as a hard error. Upgrade the core package and every companion cloud package in the same commit, or not at all.
- 4List what reads the credential.— gateway auth, redaction rules, routing middleware, test stubs. Grep for the header name across infrastructure as well as application code. Then grep your logs for the key prefix after the canary.
- 5Canary per call path.— cloud platform routes, pinned older models, and batch submissions each have their own constraints. A repo-wide rollout assumes they can all move together, and on this upgrade they cannot.
The bot was not wrong to open the pull request. It did the job it has. It just cannot read the one thing that actually changed — and neither could our review, because we had never written that thing down anywhere a reviewer could look.









