Claude models move through a lifecycle: active, then deprecated — still working, but with a published retirement date and a recommended replacement — and finally retired, at which point requests to the model fail. Retired model IDs return a 404 error, which to your application looks identical to a typo'd model name: an outage, unless you migrated first.
How deprecations are announced
Deprecations are published in Anthropic's models documentation, which lists each deprecated ID alongside its retirement date and the recommended successor. Concrete examples from the July 2026 docs give a feel for the cadence: claude-opus-4-1-20250805 is deprecated and retires on August 5, 2026, with Claude Opus 4.8 as the recommended migration; claude-3-haiku-20240307 retires April 19, 2026 in favor of claude-haiku-4-5; and claude-opus-4-20250514 and claude-sonnet-4-20250514 retire June 15, 2026. A long tail of earlier models — Claude 3.7 Sonnet, Claude 3.5 Haiku, Claude 3 Opus, and others — has already been retired and now returns 404s. The practical takeaway: someone on your team should own watching that page, the same way someone watches your database vendor's end-of-life schedule.
The 3P wrinkle: retirement differs by platform
On third-party platforms, retirement is not perfectly synchronized with the first-party API. The pricing documentation notes that Claude Opus 4 is retired except on Google Cloud, and Claude Sonnet 4 and Claude Haiku 3.5 are retired except on Amazon Bedrock and Google Cloud. So a model can be gone from the Claude API while still running in your Bedrock or Vertex AI estate. That extended availability is convenient, but do not mistake it for a plan — treat first-party deprecation as your migration trigger and any extra 3P runway as buffer. One platform is explicitly aligned: Claude Platform on AWS follows Anthropic's first-party model deprecation lifecycle and uses the same model IDs as the Claude API.
What happens on the cutoff date
Nothing graceful. Requests naming a retired ID return a 404 not_found_error, exactly as if the model never existed. There is no automatic redirect to a successor model — which is deliberate, because successors can behave differently, and silently swapping models under a production workload would be worse than failing loudly.
Why upgrades must be deliberate: pinning
Every Claude model ID is a pinned snapshot. Starting with the Claude 4.6 generation, IDs are dateless (claude-opus-4-8) but still pinned — they never silently change what they point to. Older models pair dated IDs (claude-sonnet-4-5-20250929) with convenience aliases (claude-sonnet-4-5) that resolve to the dated snapshot. Pinning means the model can only change when you change the string, and that is a feature: model upgrades are behavior changes and deserve the same rigor as a major dependency bump.
That rigor matters because migrations can carry real breaking changes. Anthropic's migration guide documents them per model pair — for example, moving from Sonnet 4.6 to Sonnet 5 means non-default temperature/top_p/top_k values now return 400 errors, and a newer tokenizer produces roughly 30% more tokens for the same text, which changes both cost and how much fits in the context window. Some pairs are painless (Opus 4.7 to Opus 4.8 has no breaking changes); you only know by reading the guide.
Make it observable
Two cheap safeguards close the loop. First, alert on 404 not_found_error responses from model endpoints specifically — that is the signature of a retirement you missed. Second, where you run on the Claude API or Claude Platform on AWS, use the Models API at startup to verify every configured ID still exists. On Bedrock, Vertex AI, and Foundry, check the provider's model catalog in its console or cloud APIs instead.
Where to go next
See why model IDs differ across platforms for the naming details, and the model lineup explained when choosing a successor tier.