Warn before retiring an address

Before you retire an address or API, announce it with Deprecation and Sunset headers.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

On the resource you are retiring, send Deprecation: @<timestamp> (RFC 9745) and Sunset: <date> (RFC 8594), with a Link to the migration notes. The sunset date comes after the deprecation date. After the sunset, answer 410 or redirect to the replacement. If you run an API, this is Required, as in deprecation headers.

Example

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://example.com/docs/api-v2>; rel="deprecation"; type="text/html"

How to check

curl -sI on the retiring address shows both headers and the link, and the migration notes answer 200.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers website playbook: https://agentwranglers.se/playbook/website/when-things-break/deprecation-and-sunset.