OpenAI's Model Deprecation and Shutdown Schedule

“Deprecated” and “shut down” are two different events with two different dates, and only one of them breaks your application. Confusing them is why teams either panic at an announcement or get a 404 they thought they had months to prepare for.

Four states, not two

OpenAI’s deprecations documentation distinguishes these, and the distinction is the useful content of the whole page:

• Current. The model is served, recommended, and is what an undated alias resolves to. Nothing to do.
• Legacy. Still served, still billable, no longer recommended, and not receiving updates. This state has no date attached and can last a long time. Traffic is unaffected.
• Deprecated. An announcement with a future shutdown date. The model still answers requests exactly as it did the day before the announcement. Nothing about your latency, your output or your bill changes. What changes is that the clock has started.
• Shut down. The id stops resolving. Requests fail; they do not silently fall back to a newer model. This is the only one of the four that is an outage.

The failure at shutdown is a 404 on the model, not a 400 on the body, and it looks roughly like this:

{
  "error": {
    "message": "The model 'text-davinci-003' has been deprecated, learn more here: https://platform.openai.com/docs/deprecations",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_not_found"
  }
}

Note that the code is model_not_found — the same code you get for a typo in the id, and the same code you get for a model your organisation has no access to. If your alerting treats model_not_found as “somebody fat-fingered the config” you will misdiagnose a shutdown on the morning it happens.

Where the dates actually live

There is exactly one authoritative list: OpenAI’s deprecations page. It is organised by announcement date, newest first, and each entry names the affected model ids, the shutdown date, and the recommended replacement. Every other list on the web, including this page, is a copy that stops being true the next time that page is edited.

Two ways to make that a habit rather than a resolution. The changelog feed on OpenAI’s developer site carries deprecation announcements, so it can go into whatever reads your other vendor feeds. And the model id that comes back in every response body — see pinning a dated snapshot — tells you what you are actually running, which is the thing you need to compare the list against.

What a completed shutdown looked like

Historical examples are more useful than a forecast, because the whole sequence is visible. Three that have fully executed:

• The original Codex models. OpenAI announced the deprecation of code-davinci-002 and its siblings in March 2023 with three days of notice, and shut them down on 23 March 2023. This is the shortest notice period in the record and the reason nobody should treat “they always give a year” as a policy.
• The first-generation completions models. Announced in July 2023 and shut down on 4 January 2024, taking text-davinci-003, the older davinci / curie / babbage / ada base models and the /v1/edits endpoint with them. Replacement was gpt-3.5-turbo-instruct for the completions shape and the chat endpoint for everything else. About six months of notice.
• The March 2023 chat snapshots. gpt-3.5-turbo-0301, gpt-4-0314 and gpt-4-32k-0314 were shut down on 13 June 2024, roughly a year after their successors shipped. This is the shape most snapshot retirements take: the alias moved long before, so the only affected callers were the ones who had pinned.

The pattern worth extracting: notice has ranged from days to over a year, and the models given days were preview or research models, while the models given a year were the ones large numbers of applications had pinned. That is a reasonable thing to plan around, but it is an observed pattern, not a published commitment.

How much notice you get

OpenAI’s stated position is that models available through the API get advance notice of shutdown, that fine-tuned models built on a deprecated base are affected alongside it, and that models in preview or beta carry weaker guarantees than generally available ones. Two consequences that catch people:

• A fine-tune is not insulation. A model you trained on a base that is being shut down goes with it, and re-running the fine-tune on a new base is a project, not a config change. If you have fine-tunes, the deprecations page is a higher-priority feed for you than for anyone else.
• Preview ids are not for production. Anything with -preview in the name is explicitly on shorter guarantees. That is what the suffix is telling you, and it applies to the reasoning previews as much as to the old gpt-4-1106-preview, whose knowledge cutoff differs from the GA Turbo snapshot as well.

There is also a state that is not on the deprecations page at all and behaves exactly like a shutdown from where you sit: a model your organisation loses access to, or never had. Access tiers, regional availability and staged rollouts all produce model_not_found on an id that is very much alive for somebody else. If a model stops working and the deprecations page says nothing, ask your own key what it can see:

curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | jq -r '.data[].id' | sort

That list is what your key can call today, which is a different and more useful question than what OpenAI serves in general.

Should a shutdown fall back automatically?

The tempting design is to catch model_not_found and retry against a newer id, so that a shutdown degrades instead of breaking. It is worth thinking about rather than reaching for, because the two failure modes are not symmetric.

Against it: a silent substitution replaces the model your prompts were tuned against, your evaluations were run against and your unit costs were computed against — at the worst possible moment, with no announcement to your own team. If the fallback works well enough that nobody notices, you now have an undocumented model in production and no record of when it arrived. That is worse than an outage you can see, because an outage ends.

For it: some workloads genuinely are model-agnostic. A classification constrained by a strict schema, a short summarisation, anything where you have already demonstrated that two models produce acceptable results. For those, refusing to fall back is pure loss.

The compromise that survives both arguments is to make the fallback loud rather than quiet: allow it, page somebody when it fires, tag every affected response with the model actually used, and treat the first occurrence as an incident rather than as the system working correctly. A shutdown never surprises anyone who was reading the deprecations page, so a fallback that fires is evidence that a process failed, not merely that a model went away.

What to do about it

The operational answer is small and boring. Log the model field from every response, so that at any moment you can produce the exact set of model ids your production traffic depends on — not the set somebody believes is in the config. Diff that set against the deprecations page on a schedule you actually keep, quarterly is enough. Keep the model id in configuration rather than in code so that the migration is a deploy and not a release. And when an announcement lands, move before the last week: the replacement will behave differently in ways your evaluation set has to catch, and that work has a variable length while the shutdown date does not.