Leaf 1 of 6
The short answer
Retiring an endpoint takes two dates, not one: the day you stop recommending it and the day it stops answering. Publish both in your docs, send both on every response, and leave a long gap between them.
RFC 9745 says the first date changes nothing about behavior: consumers can keep using the resource as before. RFC 8594 covers the second: the moment a URI is expected to become unresponsive.
Leaf 2 of 6
The two headers, side by side
This response says the version is deprecated from 1 December 2026, goes away on 1 December 2027, and where to read more:
HTTP/1.1 200 OK
Deprecation: @1796083200
Sunset: Wed, 01 Dec 2027 00:00:00 GMT
Link: <https://example.com/docs/v1-retirement>; rel="deprecation"; type="text/html"
| Deprecation | Sunset | |
|---|---|---|
| Defined in | RFC 9745, Standards Track, 2025 | RFC 8594, Informational, 2019 |
| Date format | Structured field date: @ plus Unix seconds | HTTP date |
| Meaning | Will be or has been deprecated | Expected to become unresponsive |
| Date in the past | Normal: it was deprecated then | Treat it as now: it can go at any time |
| Behavior changes | None | After the date, expect 4xx, 3xx or no answer |
Three rules catch people out. The formats differ on purpose: RFC 9745 calls it history. The Sunset date must not be earlier than the Deprecation date. And both are hints, so a client must still work if they never appear.
Formats differ in the wild too. GitHub's docs describe their Deprecation value as an HTTP date, not the @ form, so a client that parses the header should accept both.
Leaf 3 of 6
How much notice the big APIs give
No RFC sets a notice period. These are the published promises, read on 1 November 2026:
| Provider | Promise | After the end |
|---|---|---|
| GitHub REST | 24 months after a newer version ships | 410 Gone |
| Microsoft Graph | Deprecated at least 24 months before retiring | Version or API retired |
| Shopify | Each stable version at least 12 months, at least 9 months of overlap | Falls forward to the oldest accessible version |
| Anthropic models | At least 60 days for publicly released models | Requests fail |
| Stripe | Said in 2017 it had kept every version since 2011 | Pinned versions kept working |
The spread follows the cost of moving. A model swap can be one string, while a payment or commerce integration may touch code nobody has opened in years. Set your number by how hard your slowest paying customer finds the move, then publish it.
Security is the usual exception: GitHub reserves the right to act without advance notice, and Microsoft exempts service security and reliability issues.
Leaf 4 of 6
Decide what the last day does
The real choice is what a late request gets. Each option breaks differently:
Fail loudly
GitHub returns 410 Gone. The break is obvious and easy to diagnose, and it is an outage for anyone who ignored the notice. Put a link to the migration guide in the error body.
Fall forward
Shopify answers from the oldest accessible stable version. Nothing goes down, but the shape of the response may change under code that never asked for it.
Watch unversioned callers either way. GitHub says requests with no version header default to the next oldest supported version, so behavior can shift for them as old versions leave. Ask for a pinned version from the first day of your API.
Leaf 5 of 6
A 12-month calendar for a small API
This is our suggested plan, not a standard. Shorten it if every caller is a team you can reach directly.
- Before day 0
Count the callers
Log the version per API key. You cannot warn people you cannot name, and the list tells you who needs a personal email.
- Month 0
Announce and start the headers
Ship the replacement and the migration guide first. Then publish both dates in the changelog and turn on Deprecation, Sunset and the Link header.
- Month 1
Close the door to new users
Stop issuing the old version to new keys. Microsoft describes the same step: new applications may have to start on the new API soon after deprecation.
- Months 3 to 9
Email the callers still on it
Send only to keys seen on the old version, and name the endpoints each one used. A generic blast is easy to ignore.
- Month 11
Run short brownouts
Turn the old version off for a few announced minutes, in working hours. Forgotten cron jobs fail while their owners still have time to fix them.
- Month 12
Sunset, and keep the door sign up
Return
410 Gonewith a link to the guide, and keep that answer running. Check the log first: if a paying customer is still there, call them.
Leaf 6 of 6
On the client side, and common questions
RFC 8594 warns that clients that ignore the header simply see the resource vanish. Your own integrations can do better with a few lines:
const sunset = res.headers.get('sunset')
if (sunset) {
logger.warn('API sunset announced', { url: res.url, sunset })
}
Should I send a Sunset header on the replacement too?
No. Send it only on what is going away, or clients learn to ignore it.
Can a single header cover a whole API?
By default each header applies to the resource that returned it. Both RFCs allow a wider scope if you document it, though clients that have not read your docs will not know.
Is OpenAPI's deprecated flag enough?
It helps people reading the docs. Running code never sees it, so keep the headers too.



