A model name in your config looks like a pinned dependency. It isn't one in the way a locked package version is, and the gap between the two is where production surprises come from. Your product's behavior can change without a single line of your own code changing: a model is retired, a parameter stops being accepted, or you move to a newer model whose outputs differ in ways your tests never looked at.

This article uses Anthropic's published model-deprecation policy as a concrete example of how provider lifecycles work, and turns it into a checklist. Other providers run their own schedules, so read yours.

Models have a lifecycle, and it ends

Anthropic's documentation describes four states:

  • Active: fully supported and recommended.
  • Legacy: will no longer receive updates and may be deprecated in the future.
  • Deprecated: still functional but no longer recommended, with a replacement named and a retirement date assigned.
  • Retired: no longer available. Requests to a retired model fail.

The docs say deprecated models are likely to be less reliable than active ones, and that Anthropic gives at least 60 days' notice before retiring a publicly released model, by email and in the documentation.

You can see this in the real table. One Sonnet 4.5 snapshot was deprecated on September 30, 2026, with retirement set for November 30, 2026 and a named replacement. That is a roughly two-month window to find every place the identifier is used, test the replacement and ship the change. A team that never reads the notice gets a production outage on the retirement date.

The change you can't see in your diff

Retirement is loud: requests start failing. The harder risk is quieter, because moving to the replacement is a behavior change that arrives with a perfectly normal-looking deploy. Anthropic's docs also record a parameter-level example: on newer models, setting temperature, top_p or top_k to a non-default value returns a 400 error, and the recommended replacement is to guide behavior through prompting. Code that worked on one model fails on the next, and code that doesn't fail may still produce different output.

Either way, the lesson is the same: the model identifier is a dependency that moves on its provider's schedule, not yours.

A checklist that works

1. Pin to a specific model identifier in production. Use a fully qualified, dated identifier where your provider offers one, and keep any floating alias for experiments. Pinning turns an unscheduled change into a scheduled one with a visible deadline.

2. Know where you use each model. Anthropic's Console lets you export a usage CSV broken down by API key and model, which is the quickest way to find stray usage of a model that is about to retire. Whatever provider you use, put the model identifier in your own logs too, so "what changed" is a query instead of an investigation.

3. Keep a golden set. Collect a small, representative set of real inputs and write down what a good response looks like in structural terms, not exact text, since output is nondeterministic: does it call the right tool, stay within a length budget, keep required fields in structured output, avoid a failure you've fixed before. Run the candidate model against it before switching.

4. Canary the change. For anything user-facing, send a small slice of traffic to the new model behind a flag, with a one-toggle rollback to the previous identifier. A rollback should be a configuration change, not a redeploy.

5. Test early. Anthropic's own best-practice list says to test applications with newer models well before the retirement date. Do it when the replacement is announced, not in the last week.

6. Watch for the side effects. A new model can change output length, formatting, refusal behavior, latency and cost. Truncated output is a classic one: a response that now runs longer than your token limit.

The takeaway

Treat the model identifier like any third-party dependency you don't control: pin it, log it, track its end-of-life date, and test before you upgrade. The interface looks stable (same API shape, same prompt) right up until the behavior behind it isn't.

Sources

AI IntegrationAI ModelsLarge Language ModelsSoftware Engineering