- The Deprecation header says a version is, or will be, deprecated (RFC 9745).
- The Sunset header says when it is expected to stop answering (RFC 8594).
- Each can link to your notes, where partners find the way to the new version.
Sooner or later, an API version has to end. Partners built on it, some of them years ago, and some of them will not read the email you send. The hard part is rarely switching the old version off. It is making sure the people who depend on it have heard, and know where to go next.
HTTP has two standard response headers for exactly this message. One says that a version is deprecated. The other says when it is expected to stop answering. Both travel with every response the old version sends, so they reach the partner’s software even when the announcement never reached a person.
This guide explains what each header says, in plain terms, with the RFC linked beside each point so you can check it yourself. It is not legal or contract advice.
Two headers for two moments
The Deprecation header marks the moment a version stops being the one to build on. The Sunset header marks the moment it is expected to stop working.
RFC 8594 describes this split itself. Deprecation of a Web API, it says, often happens in two stages: first the API is no longer the preferred or recommended version, then it is decommissioned. In the first stage the API remains operational, and the RFC says the Sunset header is not appropriate there. It is meant for the second stage, when the API or a version of it does become unresponsive.
What the Deprecation header says
RFC 9745, “The Deprecation HTTP Response Header Field”, was published in March 2025 in the Standards Track. It lets a server tell a client application that a resource is deprecated, or will be.
The header carries a date. A date in the future means the resource will be deprecated then; a date in the past means it has been deprecated since then. The RFC’s own example, Deprecation: @1688169599, stands for 30 June 2023 at 23:59:59 UTC (RFC 9745).
The most useful sentence for a product leader is a short one: the act of deprecation does not change any behavior of the resource (RFC 9745). Partners can keep using a deprecated version as before. What deprecation does, in the RFC’s words, is encourage client applications to migrate away, discourage new dependencies on the resource and inform applications about the risk of continued dependence upon it.
What the Sunset header says
RFC 8594, “The Sunset HTTP Header Field”, was published in May 2019 as an Informational RFC. It defines a header with a single timestamp: the point in time when the resource is expected to become unresponsive.
The timestamp is an HTTP date, such as Sunset: Sat, 31 Dec 2018 23:59:59 GMT, and it should lie in the future. If it lies in the past, the RFC says the safest reading is the present: the resource can become unavailable at any time (RFC 8594).
After the sunset, the RFC expects that partners are likely to get client errors, redirects or no answer at all, and the header does not say which of these to expect (RFC 8594).
How the two fit together
Used together, the sunset date may not come before the deprecation date. RFC 9745 states that the Sunset timestamp must not be earlier than the Deprecation one, and that a partner who sees otherwise should ask the provider for clarification. The two headers write their dates differently, for historical reasons the RFC mentions, so a response can carry Deprecation: @1688169599 beside Sunset: Sun, 30 Jun 2024 23:59:59 UTC.
Both headers apply to the resource that returns them. Both RFCs allow an API to give them a wider reach, for example announcing the end of a whole version on its home document, and say that such a wider scope is usually documented. They also warn that partners who don’t know the rule will read the header as being about that one resource only (RFC 9745, RFC 8594).
The link to your migration notes
A date alone tells a partner that something is ending. The link tells them what to do about it, and that is where your real message lives.
RFC 9745 defines a deprecation link relation that points to documentation about the deprecation. It can be published before the deprecation, to make the policy easy to find, and the RFC places no restriction on its form. That documentation may give a guide and a timeline for moving to a new resource. RFC 8594 defines a sunset link relation for the same purpose: the sunset policy, details of an upcoming sunset, and ways for users to move elsewhere.
So the page behind the link is a product decision, not a technical one. It is where you state the date you announce, what replaces the old version and what a partner needs to change.
What the headers don’t do
Both headers are hints. RFC 8594 asks clients to treat the sunset timestamp as one: the resource is not guaranteed to be available until then, nor to be gone afterwards. RFC 9745 calls deprecation information optional information that cannot be depended on.
They also only reach software that reads them. A client that ignores the Sunset header carries on as usual, and may simply find the resource gone without having noticed the warning (RFC 8594).
Neither RFC sets how much notice to give. That choice, and any promise your partner agreements make about it, is yours and your advisers’.
What stays with you
The headers carry a message. Deciding the message is the product work, and it comes down to a handful of choices.
The date. Which day you announce, and whether you can hold to it once partners have planned around it.
The replacement. Whether the new version is in place, and does what partners need, before you ask anyone to move.
The notes. One page that says what changes, what replaces what, and whom to ask.
The people. Which partners deserve a conversation, not just a header and an email.
Get those right and the headers do what they were written for: they carry your word to every partner that still calls the old version, steadily, until the day you named.
Where we come in
This guide describes two public standards. We make no promise about how any partner’s software reads them.
If an old version of your own API has to end, Retire an old API version without stranding your partners describes that work: the new version in place first, then the old one retired on the date your partners were told.
It starts with a conversation, with no obligation. If you would like to talk it through, let’s talk.
