Sunset
The HTTP Sunset response header indicates the date and time when a URI will become unresponsive or 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: Fri, 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"
Takeaway
The Sunset header communicates a specific date and time when a resource will become unavailable, enabling clients to prepare for service changes or plan migrations before the removal date.