Model deprecations - how to avoid breakage when a model is retired

A model id is not forever. The day a provider flips a model from "deprecated" to "retired," every request you send to that id starts returning errors. If your app hardcodes a single model string, that is a production outage with a calendar date attached. The good news: deprecations are announced in advance, and a little architecture goes a long way.

Deprecation is not retirement

Most providers separate the two stages, and the distinction matters.

• Deprecated means the model still works, but it is no longer recommended and has a scheduled shutdown date. This is your migration window.
• Retired means requests fail. The id is gone from the API.

According to OpenAI's API deprecations documentation, when a model is deprecated it immediately gets a shutdown date, and the company commits to a minimum of six months' notice before retiring a generally available model unless safety or compliance forces a faster timeline. Anthropic's model deprecations docs describe a four-stage lifecycle (active, legacy, deprecated, retired) and commit to at least 60 days' notice before retiring a publicly released model. Different vendors, different clocks.

This is happening more often, not less

The pace has accelerated sharply. OpenAI deprecated gpt-4.5-preview on April 14, 2025 and removed it from the API on July 14, 2025 (per the OpenAI developer community deprecation thread). On the Anthropic side, Claude Opus 3 was notified for retirement on June 30, 2025 and retired July 21, 2025, and Claude Sonnet 3.5 was retired January 5, 2026, according to Anthropic's model deprecations page. Forbes reported in November 2025 that Anthropic had committed to preserving the weights of retired models, in the context of the company retiring multiple Claude models within a year.

The takeaway is not any single date. It is the trend: model ids you depend on today have a shelf life measured in months, and "it worked last quarter" is no longer a safety guarantee.

How to build so a retirement is a config change

The core principle is to treat the model id as configuration, never as a constant baked across your codebase.

1. Centralize the model id. One environment variable or config key, read in one place. Swapping gpt-4o for its successor should be a one-line diff, not a find-and-replace across forty files.
2. Subscribe to deprecation notices. Providers email impacted accounts and publish docs pages. Put the renewal date in your team calendar the moment you read the email.
3. Test the replacement before the deadline. Prompts are not perfectly portable. Re-run your evals against the successor model so you catch regressions in tone, formatting, or tool-calling on your schedule, not the provider's.
4. Keep a fallback path. If your primary model id ever returns an error, your code should be able to retry against an alternate model or provider instead of failing the user request.

The hard part of step 4 is usually plumbing: every provider has a different SDK, base URL, and auth scheme, so a "fallback" often means a second integration.

One endpoint makes the fallback trivial

This is where a unified gateway removes most of the migration pain. With AnyModel, you call one OpenAI-compatible endpoint and reach GPT, Claude, Gemini, DeepSeek, GLM, Kimi, Qwen, and Grok with a single API key. Switching models — whether because one was retired or because a newer one is better — means changing the "model" field and nothing else.

curl https://anymodel.org/v1/chat/completions \
  -H "Authorization: Bearer $ANYMODEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4.5","messages":[{"role":"user","content":"hi"}]}'

When a model id is retired, you do not rewrite an integration or add a new SDK — you point the same config key at a different string. Because every model lives behind the same base URL (https://anymodel.org/v1), a fallback to a different vendor is just another model id, not another project. You can browse what is currently available on the models page and weigh successors side by side on the compare page before you commit.

Start migration-proofing today

Deprecations will keep coming. The apps that ride them out are the ones where the model is a variable, not a hardcoded assumption. Get a key, point your client at one endpoint, and make "switch models" a non-event.

Create a free AnyModel account — 1,000,000 tokens to start (6,000,000 if you link Telegram), no credit card, no subscription. Prefer to keep prompts off our servers? Turn on Ghost Mode for zero-retention keys. More reliability deep-dives live on the blog.