Sunset general response

What it does

Sunset announces a specific future date after which a resource is expected to stop being available entirely. It's the machine-readable version of an API changelog entry saying "this endpoint will be removed on X date" — instead of (or alongside) documentation prose, clients and automated tooling can programmatically detect an approaching retirement date and act on it, whether that's alerting a developer, logging a warning, or triggering an automated migration workflow.

It's commonly paired with Deprecation (which signals a resource is already deprecated, without necessarily specifying an exact removal date) and often a Link header pointing to migration documentation.

Syntax

Sunset: <HTTP-date>

Example:

Sunset: Wed, 01 Jan 2027 00:00:00 GMT

The value follows the standard HTTP date format, same as Date, Expires, and Last-Modified.

How it's used in practice

• API version retirement announcements — a versioned API endpoint scheduled for shutdown includes Sunset on every response, giving API consumers a concrete, checkable deadline rather than relying solely on advance email announcements or documentation that might go unread.
• Combined with Link for migration guidance — pairing Sunset with a Link: <migration-docs-url>; rel="sunset" gives both the "when" and the "what to do about it" in machine-readable form.
• Automated monitoring and alerting — API client libraries or internal tooling can watch for Sunset headers on responses and automatically flag or alert when a dependency is approaching its retirement date, catching deprecated API usage before it becomes an outage.
• Gradual, staged endpoint retirement — some APIs use Sunset well in advance (months) to give consumers ample migration time, then eventually return 410 Gone once the sunset date actually passes.

Common mistakes and gotchas

Setting Sunset without also communicating why or what to migrate to. A bare date with no accompanying context (documentation link, deprecation notice explaining the replacement) leaves API consumers knowing when something breaks but not what to do about it — pairing with Deprecation and a Link to migration docs is much more actionable.

Announcing a sunset date too close to the actual change. Giving API consumers insufficient lead time defeats much of the purpose — the whole value of Sunset is giving automated tooling and human developers enough advance warning to plan and execute a migration before the deadline arrives.

Not actually enforcing the sunset date. If a Sunset date passes and the resource keeps working indefinitely anyway, API consumers learn (correctly, from observed behavior) that your sunset dates aren't reliable signals — undermining trust in the header for any future deprecations you announce.

Confusing Sunset with Retry-After. They're superficially similar (both communicate a future point in time) but serve opposite purposes — Retry-After tells a client when a currently unavailable resource might become available again; Sunset tells a client when a currently available resource will stop being available.

Real-world examples

API version approaching retirement:

HTTP/1.1 200 OK
Sunset: Wed, 01 Jan 2027 00:00:00 GMT
Deprecation: true
Link: <https://api.example.com/docs/migration-v2>; rel="sunset"

Response after the sunset date has passed:

HTTP/1.1 410 Gone
Link: <https://api.example.com/docs/migration-v2>; rel="sunset"

FAQ

What's the difference between Sunset and Deprecation?

Deprecation signals that a resource is deprecated (generally, without necessarily specifying an exact removal date — it can just be a boolean or a deprecation-since date). Sunset specifically announces a future date when the resource will stop being available. They're often used together: Deprecation says "this is on its way out," Sunset says "specifically, by this date."

Does setting Sunset automatically make the resource stop working on that date?

No — the header is purely informational/advisory. Actually retiring the endpoint (returning 410 Gone or similar after the sunset date) is a separate implementation step you need to handle explicitly; the header doesn't enforce anything on its own.

How far in advance should I set a Sunset date?

There's no fixed rule, but giving substantial lead time (weeks to months, depending on how disruptive the change is and how many consumers depend on it) is generally good practice — the whole point of the header is giving consumers time to react before something breaks.

Should I combine Sunset with a Link header?

Strongly recommended — a bare date tells consumers when something changes but not what to do; pairing with a Link to migration documentation or a replacement resource makes the deprecation actionable rather than just informational.

Fun fact

Sunset and Deprecation were standardized relatively late in HTTP's history (RFC 8594 for Sunset was published in 2019) despite API versioning and deprecation being a problem developers had been solving with ad-hoc conventions (custom headers, changelog emails, documentation banners) for the entire preceding history of the web API era. It's a good example of HTTP standardization often lagging well behind real-world practice — by the time these headers were formalized, plenty of major API providers had already been solving the same problem with their own bespoke, incompatible conventions for years.