---
title: "Warn before retiring an address · Agent Wranglers"
url: https://agentwranglers.se/playbook/website/when-things-break/deprecation-and-sunset
updated: 2026-10-20
licence: "All rights reserved"
---

# Warn before retiring an address

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Optional
- Chapter: [When things break](https://agentwranglers.se/playbook/website/when-things-break)
- Rule: Before you retire an address or API, announce it with `Deprecation` and `Sunset` headers.
- How: 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](https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers).
- Check: `curl -sI` on the retiring address shows both headers and the link, and the migration notes answer 200.

Example:

```http
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"
```

**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`.

- Previous: [Let people install the site](https://agentwranglers.se/playbook/website/when-things-break/pwa-manifest)
- Next: [Serve the last good page when the server fails](https://agentwranglers.se/playbook/website/when-things-break/serve-stale-on-error)
- [When things break](https://agentwranglers.se/playbook/website/when-things-break)