Anthropic gives at least 60 days’ notice before retiring a model, and once the retirement date passes, API requests to that model fail outright — there’s no quiet grace period. Several widely used Claude models are already deprecated or retired as of this writing, each with a recommended replacement, so if your code pins a specific model string, it’s worth checking it against the current list before it breaks in production.
What “deprecated” and “retired” actually mean
These are two different states, and the difference matters for how urgently you need to act. Per Anthropic’s model deprecation documentation, a deprecated model still works but is “likely to be less reliable than active models” — it’s a warning window, not a shutoff. A retired model is past its retirement date, and “requests to models past the retirement date will fail” outright. Anthropic notifies customers with active deployments ahead of the retirement date, with that 60-day minimum window for publicly released models.
Models currently deprecated or retired, per Anthropic’s own table
This is a snapshot of the status table as documented — always check the live page for the current state, since retirement dates are added to it on a rolling basis:
| Model | Status | Deprecated | Retirement date | Recommended replacement |
|---|---|---|---|---|
| claude-sonnet-4-5-20250929 | Deprecated | September 30, 2026 | November 30, 2026 | claude-sonnet-5-5 |
| claude-opus-4-1-20250805 | Retired | June 5, 2026 | August 5, 2026 | claude-opus-4-8 |
| claude-sonnet-4-20250514 | Retired | April 14, 2026 | June 15, 2026 | claude-sonnet-4-6 |
| claude-opus-4-20250514 | Retired | April 14, 2026 | June 15, 2026 | claude-opus-4-8 |
| claude-3-haiku-20240307 | Retired | February 19, 2026 | April 20, 2026 | claude-haiku-4-5-20251001 |
| claude-3-5-haiku-20241022 | Retired | December 19, 2025 | February 19, 2026 | claude-haiku-4-5-20251001 |
| claude-3-7-sonnet-20250219 | Retired | October 28, 2025 | February 19, 2026 | claude-sonnet-4-6 |
Each entry in Anthropic’s own table comes with that recommended-replacement column, which is the single most useful piece of information if you’re triaging what to update first — it tells you not just that a model is going away, but what Anthropic itself suggests swapping it for. Note that the same replacement often covers several retired versions: both deprecated Sonnet 4 snapshots above point to claude-sonnet-4-6, for instance, so one migration can close out more than one line in your grep results.
What actually happens when you call a model past its retirement date
The deprecations page states plainly that “requests to models past the retirement date will fail,” but it doesn’t spell out the exact error shape on that page. Anthropic’s API errors reference documents the general-purpose not_found_error, returned with HTTP status 404, for “the requested resource was not found” — which covers an unrecognized endpoint or resource ID in a request. A retired model string falls into exactly that category once it’s gone: it’s an ID the API no longer resolves to anything, not a request that was malformed in some other way. Practically, that means your error-handling code should treat a model-related 404 as a signal to stop and fix the code, not to retry — the same way you’d treat an authentication failure — since no amount of retrying resolves an ID that no longer exists.
Finding every place your codebase pins a model string
A model name often ends up hardcoded in more places than the one obvious API call — config files, test fixtures, CI scripts, and documentation examples all tend to collect a copy. A quick repo-wide search surfaces them before you rely on finding them one at a time during an incident:
grep -rn "claude-[a-z0-9-]*-[0-9]\{8\}" --include="*.py" --include="*.js" --include="*.ts" --include="*.json" --include="*.yaml" --include="*.yml" .
This pattern matches the dated model-string format Anthropic uses (like claude-sonnet-4-5-20250929), across the file types most likely to reference one. Running it before a migration turns “did we catch everywhere?” into a list you can check off, rather than a guess — and it’s worth adding as a step to the same CI/CD pipeline that already runs your other checks, so a newly deprecated model shows up as a build warning instead of a silent surprise.
How Anthropic notifies you — and the audit tool most people miss
You don’t have to catch a retirement date by re-reading the documentation page on a schedule. Per the deprecations page, “impacted customers will always be notified by email and in the documentation” once a model they’re actively using has an upcoming retirement. More useful than the email itself is a feature buried in the Console: go to the Usage page, click Export, and the downloaded CSV breaks usage down by API key and model — so instead of guessing which key or service is still calling a soon-to-retire model, you get a direct answer from your own traffic. Pair that export with the grep command above and you’ve covered both places a stale model reference tends to hide: the code you can search, and the running traffic you can’t see just by reading files.
Pinned dates versus floating aliases
A dated model string like claude-opus-4-1-20250805 is precise — your output quality and behavior don’t shift under you between requests — but it also means you own tracking its retirement date yourself. For some model families, the undated alternative is a genuine alias: Anthropic’s documentation on model IDs describes a shorter form like claude-sonnet-4-5 as a convenience pointer that “point[s] to the most recent dated snapshot for that minor version,” meaning the behavior behind it can shift when Anthropic updates what the alias resolves to. That’s no longer true across the board, though — for newer model lines, the documentation is explicit that the dateless ID “is not an alias. It is the snapshot,” fixed to “a single, fixed model snapshot” that Anthropic does not update once released. In other words, whether an undated model string is a moving target or a permanent pin now depends on which generation it belongs to, which makes checking the current model-IDs documentation for your specific model family more useful than assuming either behavior by default.
Neither pinning nor relying on a true alias is universally correct where one is still available as a moving pointer; a pinned date suits a workload where reproducible output matters more than zero-maintenance updates, like evaluation suites or regulated outputs, while a floating reference suits a workload where staying current matters more than pinning exact behavior, like a general-purpose chat feature. Whichever you choose, the model card for the version you land on is still worth reading before you commit to it.
A migration checklist
- Run the grep above (or your language’s equivalent) across the full repo, not just the obvious API wrapper file.
- Check each match against the current deprecation table, not a cached memory of it — the table changes as new retirement dates are announced.
- For each deprecated model found, note Anthropic’s recommended replacement rather than picking a newer model at random — a recommended replacement is chosen for behavioral continuity, not just recency.
- Re-run your existing evaluation suite against the replacement before swapping it in production, especially for anything that depends on specific output formatting or tone, since model evaluation is exactly what catches a subtle regression a changelog won’t mention.
- Set a recurring calendar reminder to re-check the deprecation table — there’s no webhook or push notification for this, so a model you pinned eight months ago can approach retirement with nothing in your inbox to flag it.
Why this is worth automating, not checking manually
If you’re already calling the API on a schedule — the kind of setup covered in scheduling a recurring Claude API call with cron — the same job is a natural place to log which model string was used on each run, so a deprecation doesn’t surface for the first time as a string of failed jobs. A model router that selects between models dynamically, the approach covered in what an AI model router is, sidesteps some of this by design, but even a router needs its own list of allowed models kept current against the deprecation table — the problem moves, it doesn’t disappear.
What happens to a model after it’s retired
Retirement doesn’t mean the model disappears entirely on Anthropic’s side, even though it stops answering API requests. In a public commitments document, Anthropic states it is “committing to preserve the weights of all publicly released models, and all models that are deployed for significant internal use moving forward for, at minimum, the lifetime of Anthropic as a company,” and that for each deprecated model it will produce a “post-deployment report,” preserved alongside the weights, that includes “interview[ing] the model about its own development, use, and deployment.” The same document is candid about why retirement happens at all: “we aren’t currently able to avoid deprecating and retiring models altogether,” since keeping every past model running in production scales the serving burden with every new release. None of that changes the practical reality for your code — a preserved weight isn’t a live endpoint — but it does mean a retired model ID isn’t being deleted from existence, just taken out of public API service.
FAQ
Can I get continued access to a model after it’s retired?
There’s no standing, documented program guaranteeing this, but it isn’t unprecedented: when Claude Opus 3 was retired from the API, Anthropic kept it available on claude.ai for paid subscribers and offered API access on request through a form linked from its retirement announcement, saying it intended to “grant access liberally.” Treat that as a case-by-case exception you’d have to ask for, not a default you can plan around.
Will I get a warning before a model I’m actively using gets retired, or do I have to check the docs myself?
Per Anthropic’s deprecations page, customers with active deployments on a model get a notice at least 60 days before its retirement date, delivered “by email and in the documentation.” That’s a floor, not something you need to poll for — though the Console usage export above is still worth running yourself if you want to confirm no key slipped through unnoticed, rather than relying solely on an email reaching the right inbox.
