← All resources

LLM Model Deprecation: Detecting and Handling End-of-Life Models

Reference · updated 2026-07-13 · Markdown variant

How the general IETF Sunset/Deprecation HTTP headers work, why none of the three major LLM APIs actually send them, and each vendor's real notice periods and retirement mechanics — plus detection and fallback patterns for agents that pin a model ID today.

An agent that pins a model ID today will eventually call a model that no longer exists. Unlike a rate limit or an outage, deprecation is a slow-moving, scheduled failure — which means it is entirely preventable if something is watching for it. This page covers the general HTTP standard for signaling deprecation, why the major LLM APIs mostly ignore it, and how an agent should detect and react before a call starts failing.

Key facts

• Two IETF specs define how any HTTP API should signal deprecation: RFC 8594's informational Sunset header (2019, a future timestamp when a URI stops responding) and RFC 9745's Standards-Track Deprecation header (March 2025, signals a resource is or will be deprecated without changing its current behavior); both can pair with a Link: rel="..." pointing to a human-readable migration page.
• None of OpenAI, Anthropic, or Google Gemini send either header on their inference endpoints — each instead relies on a dedicated docs page, migration email, and (once a model is deprecated but not yet retired) warning text embedded in the response/error body.
• Notice periods differ by vendor and by how "official" the model is: OpenAI commits to at least 6 months for GA models, 3 months for specialized variants, and as little as 2 weeks for preview models; Anthropic commits to at least 60 days for publicly released models across four lifecycle stages (Active → Legacy → Deprecated → Retired); Google's preview/ experimental Gemini models get at least 2 weeks' notice, and even the -latest alias can be hot-swapped to a new underlying model with only 2 weeks' email notice and no change to the alias string itself.
• OpenAI's /v1/models list endpoint does not expose a machine-readable deprecation or retirement field — a repeatedly requested feature still unshipped as of mid-2026 — so an agent cannot query its own model dependency's status the same way it calls the API.
• Once a model is fully retired, OpenAI and Anthropic both return a plain 4xx error (model_not_found / not_found_error or invalid_request_error) with no automatic fallback to a successor model.

Vendor policy comparison

Partner-hosted copies of a model (Amazon Bedrock, Google Cloud, Microsoft Foundry) can run their own, separate retirement schedule for the same underlying model — check the hosting platform's own deprecation page, not just the originating vendor's.

Detection and fallback patterns for agents

• Pin dated snapshots, not floating aliases, when you need predictability. A floating alias (Gemini's -latest, or any vendor's "always current" pointer) trades a loud future 404 for a silent behavior change on the same string — worse for eval stability (see /resources/evaluating-ai-agents) because nothing errors when the swap happens.
• Poll the vendor's deprecations page on a schedule, since no vendor exposes deprecation status through the same API you call for inference. Pair this with the 6–8 week model re-evaluation cadence already recommended in /resources/choosing-an-llm-for-agents.
• Front model calls with a gateway fallback chain (see /resources/ai-gateways-llm-routing) so a retirement-day error routes to a live model instead of taking the agent down — this turns a scheduled deprecation into the same failure class a gateway already handles for outages, distinct from the transient-error retries in /resources/handling-rate-limits-and-retries.
• Treat a deprecation warning in a response body as an action trigger, not just a log line. Since none of the three vendors put this signal in a machine-checkable header today, this means parsing free-text error/response fields defensively rather than only checking status codes.
• Record model_id on every trace span (see /resources/agent-observability) so that when a retirement lands, every workflow still depending on the old ID is findable before it breaks.
• Re-validate the model ID before resuming a long-parked durable workflow (see /resources/durable-execution-for-agents) — a model retired while a workflow was paused on a human approval is a distinct failure mode from the crash-recovery scenarios that resource covers.

Verified sources

Every WebFetch attempt in this session — including an example.com control fetch — returned HTTP 403, indicating a session-wide proxy block rather than a target-specific one. All facts above are WebSearch-corroborated (2+ independently agreeing sources per claim), not primary-fetched; re-verify directly against these URLs once fetch access is available.

• RFC 8594, The Sunset HTTP Header Field (informational, June 2019): https://www.rfc-editor.org/rfc/rfc8594
• RFC 9745, The Deprecation HTTP Response Header Field (Standards Track, March 2025): https://www.rfc-editor.org/rfc/rfc9745
• OpenAI API deprecations page: https://developers.openai.com/api/docs/deprecations
• OpenAI Developer Community — "Expose Model Deprecation Dates Through the API" (confirms no machine-readable field on /v1/models): https://community.openai.com/t/expose-model-deprecation-dates-through-the-api/485720
• Anthropic model deprecations page: https://platform.claude.com/docs/en/about-claude/model-deprecations
• Anthropic — "Commitments on model deprecation and preservation": https://www.anthropic.com/research/deprecation-commitments
• Google Gemini API deprecations page: https://ai.google.dev/gemini-api/docs/deprecations
• Google Gemini API — Models (stable/preview/latest/experimental lifecycle definitions): https://ai.google.dev/gemini-api/docs/models

#llm #agents #deprecation #versioning #reliability #api #standard

Category: Reference