What is model deprecation — and why your AI app breaks on a calendar date

Your bot ran for six months. You changed nothing. Then one day it errors on every request.
That's not a hack and not a bug. The model you were calling was switched off — and the date was announced months ago. The email just went to the address you registered the key with, and you scrolled past it.
Here's what's strange about this kind of breakage: it's scheduled. Models have an expiry date, and it's in the docs before you even start writing code.
Models live on a schedule
The big providers describe the lifecycle almost identically. Anthropic, for example, uses four states:
- Active — supported and recommended.
- Legacy — no more updates, deprecation possible.
- Deprecated — still works, no longer recommended; a replacement and a retirement date are already assigned.
- Retired — done. The docs say it plainly: requests to a retired model will fail.
The key point is that deprecation is not shutdown. Deprecation is the warning: the model still answers, but the clock is running. Retirement is the moment your code falls over.
How much time you get
Providers publish minimum notice periods. At OpenAI, generally available models get at least 6 months, and specialized variants (chat versions, codex versions, deep research) get at least 3 months. They notify the customers actually using the model: by email, on a dedicated deprecations page, and via a blog post for larger changes.
This isn't abstract. On August 5, 2026 Anthropic retired Claude Opus 4.1 — the release notes state directly that requests to it now return an error. In February 2026 OpenAI removed GPT‑4o, GPT‑4.1 and o4‑mini from ChatGPT, while o3 and GPT‑4.5 went through a 90-day sunset period.
There are reversals too: GPT‑4o was once deprecated and then brought back, because a group of users asked for more time to migrate. But building a product on "maybe they'll bring it back" is a bad bet.
And a small trap for anyone reaching models through a cloud: partner platforms set their own dates. The same model can still be active at one provider and already retired at another. Check the table for whoever you actually call.
The quiet breakage — the worse one
A loud "model not found" is, oddly, the good case. You see instantly what happened and know what to fix.
It's worse when nothing fails.
Model identifiers come in two flavours. A pinned one names a specific version: Anthropic's docs say the underlying model stays constant for the lifetime of that id. And an alias like "latest of this family" points at the current version and moves when a new one ships.
Aliases are convenient: upgrades arrive on their own. But one morning your code starts answering differently — different tone, different length, different JSON shape. No errors, clean logs, and the prompts you polished for a week now work slightly worse. You don't catch that with an alert; you catch it from user complaints two weeks later.
The conclusion is simple: pin the version explicitly in production and migrate deliberately. Aliases are for experiments, where a surprise costs nothing.
Four cheap things to do in advance
- Keep the model name in one place. An environment variable or a config, not fifteen hardcoded strings. Migrating should be a one-line edit, not archaeology.
- Keep a tiny test set. Twenty real "input → expected answer" pairs. That's an eval — with it, swapping models turns from faith into a ten-minute check.
- Subscribe to the provider's changelog. The deprecations page updates long before your code breaks. Skimming it monthly is cheaper than firefighting.
- Plan a fallback. If the main model is unavailable, try a second one and log it. That also covers temporary outages, not just retirements.
You can't avoid paying for model churn entirely: it's the industry's rhythm, not a bug. But the difference between "migrated in an evening" and "production is on fire" is exactly these four steps — and they're done before the email arrives. They'll also serve you the next time you're choosing a model for a task.
Are deprecation and retirement the same thing?
No, and confusing them is expensive. Deprecation is the announcement: the model works, but a date and a replacement are set. Retirement is that date, after which requests fail.
The model disappeared from the chat app but still works in the API. Why?
Because those are two products on two schedules. A model can be pulled from an interface where almost nobody uses it and kept in the API, where removing it breaks other people's code — so the timelines differ.
Is retirement related to the model's training date?
No, different things. The knowledge cutoff tells you how far the model's picture of the world goes; deprecation tells you how long it answers at all.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





