Sunsetting an API version without breaking clients is a communication problem wearing an engineering costume. The technical part — versioning, routing, eventually deleting code — is straightforward. The part that actually determines whether clients break is whether they knew the change was coming, had enough time to act on it, and could tell from their own logs that they were still affected. Get that right and the shutdown is uneventful. Get it wrong and you spend a week fielding incident reports from integrators who never saw the announcement.
What changed in 2026
- The Deprecation and Sunset HTTP headers, defined in IETF specifications, are now widely implemented, letting client tooling and API gateways flag outdated calls automatically instead of relying on a changelog someone has to remember to read.
- Per-client usage dashboards became standard on API platforms, so providers can see exactly which API keys or clients are still hitting a deprecated version instead of guessing from aggregate traffic.
- Automatic migration proxies grew more common — a compatibility layer that translates old-version requests to the new version under the hood, buying time without extending the deprecated code path's actual lifetime.
- Version support windows got explicit and public. Many API providers now publish a fixed support duration, such as 18 months per major version, so clients can plan migrations proactively instead of reacting to surprise notices.
The three-phase timeline
| Phase |
What happens |
Typical duration |
| Announce |
New version ships; old version still fully supported |
Starts immediately at new version launch |
| Deprecate |
Old version works but is flagged (headers, docs, dashboard warnings); no new features land on it |
6-18 months, usage-dependent |
| Sunset |
Old version stops working, returns errors or redirects |
After the deprecation window, contingent on usage dropping |
Do not compress this into "we shipped v2, v1 is gone in 30 days." Clients need real time to notice, plan, test, and ship their own migration.
How to execute it
- Ship the new version and a compatibility layer together, so a client migrating early is not blocked on missing functionality in the new version.
- Add Deprecation and Sunset response headers to the old version's responses immediately, with a machine-parseable date, even before you email anyone.
- Identify active callers from usage data, not just documentation views. Reach out directly to the accounts still generating meaningful traffic on the old version.
- Publish a fixed sunset date once usage justifies it, and hold that date only after direct outreach to remaining callers, with a grace extension process for clients actively migrating in good faith.
- Return a clear, actionable error after sunset — a 410 Gone with a link to migration docs, not a silent failure or a generic 500.
Common mistakes
Announcing only in a changelog or blog post. Most integrators do not monitor either. Email active API key holders directly, and add in-band signals like response headers that their own tooling can catch.
Picking a sunset date before checking usage. A calendar date with no regard for active traffic guarantees you will break someone. Extend for real, actively migrating clients rather than enforcing the original date rigidly.
Removing the old version the instant a dashboard shows near-zero traffic. Near-zero is not zero, and the remaining caller may be running something critical that only fires monthly or during an incident.
No machine-readable signal, only human-readable docs. Response headers such as Deprecation, Sunset, and a Link header with rel="deprecation" let client code and monitoring systems catch the change automatically, which scales far better than hoping every integrator reads your docs.
FAQ
How long should an API deprecation window be?
Commonly 6 to 18 months, depending on how embedded the API is in client systems. Internal APIs with a handful of known callers can move faster; public APIs with unknown third-party integrators need longer.
What HTTP headers should a deprecated endpoint return?
Deprecation, a date or boolean signaling deprecated status, and Sunset, the date it will stop working. Both are defined in IETF specifications and increasingly supported by API tooling and gateways.
What should happen when a client calls a sunset endpoint?
Return a clear error, typically 410 Gone, with a response body pointing to migration documentation, not a silent failure, a generic 500, or a redirect that hides the fact the version is gone.
How do I find out who is still using an old API version?
Instrument per-client usage metrics, by API key, token, or client ID, rather than relying on aggregate traffic graphs. This is what lets you contact specific integrators instead of broadcasting to everyone.
Where to go next
For the routing pattern behind incrementally moving traffic off an old system, see the strangler pattern for legacy migration in 2026. If retried requests to your API need to be safe during the migration window, see idempotency keys explained in 2026. For notifying integrators directly, how to send emails from an app in 2026 covers the delivery side.