Sunset
When an API endpoint or resource is scheduled for removal, the Sunset response header communicates the date and time after which the URI will become unavailable.
Usage
The Sunset header provides advance notice to clients about scheduled resource removal or service shutdown. Servers include this header in responses to communicate a specific timestamp after which the resource will no longer be available. The header value is an HTTP-date in IMF-fixdate format, the same date format used by Retry-After and other timing-related headers.
API providers use Sunset to signal endpoint deprecation timelines,
giving client applications time to migrate to alternative endpoints before
the removal date. Archive systems use the header to communicate retention
policies, such as resources stored for a fixed period before automatic
deletion. The header works alongside the Link header with the
sunset relation type, which points to documentation explaining the
deprecation or sunset plan.
The presence of the Sunset header does not change resource behavior or responses. The resource continues functioning normally until the specified date. After the sunset date passes, the server typically responds with 410 Gone or stops responding entirely, depending on the implementation.
The Sunset header is often paired with the Deprecation header to signal both the deprecation status and the planned removal date. Deprecation marks the start of the deprecation period, while Sunset marks the end when the resource becomes unavailable.
Values
HTTP-date
The value is an HTTP-date timestamp in IMF-fixdate format, expressed in
GMT. The format follows the pattern Day, DD Mon YYYY HH:MM:SS GMT, such
as Wed, 11 Nov 2026 11:11:11 GMT.
Example
A resource scheduled for removal on November 11, 2026 includes the sunset timestamp in the response. The date indicates when the server will stop serving this resource.
Sunset: Wed, 11 Nov 2026 11:11:11 GMT
An API endpoint being phased out includes both Sunset and Link headers. The Link header points to migration documentation explaining the replacement endpoint and transition plan.
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.re/docs/migration>; rel="sunset"
A deprecated endpoint combines Deprecation and Sunset headers to communicate both the deprecation notice and the planned removal date. Clients see when deprecation began and when complete removal occurs.
Deprecation: @1735689600
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.re/docs/v2-migration>; rel="sunset"
Planning the removal
The header announces a date and changes nothing on its own, so the removal still needs a deliberate response once the date passes. 410 states the resource is gone permanently and belongs on endpoints with no replacement. 301 belongs on endpoints with a direct successor, and sending the redirect before the sunset date gives clients a working path throughout the transition rather than a cliff. 404 communicates less, since the absence reads as accidental rather than planned.
Announcement value depends on clients reading response headers, and most do not. Traffic logs filtered to the deprecated path show which callers remain and whether the date is realistic. A sunset date arriving with substantial traffic still on the endpoint indicates the announcement never reached anyone, and removal on schedule breaks those callers regardless of the notice period.
Pairing carries the full picture.
Deprecation marks when the endpoint
stopped being recommended, Sunset marks when the
endpoint stops responding, and a Link header
with
rel="sunset" points at the migration path. The
three together let a client detect the state, find
the replacement, and schedule the work without
reading a changelog.
Search engines and Sunset
Search engines ignore the Sunset header. A page carrying a sunset date stays indexed and ranking normally until the URL starts returning something else, so the header offers no way to prepare search engines for a planned removal.
Ranking signals transfer through a 301 to the replacement URL, which is the reason to publish the redirect at the sunset date rather than 410 on any URL holding traffic or links. Reserve 410 for endpoints with no successor, where removal from the index is the intended outcome.
