---
title: "Warn before retiring an address · Agent Wranglers"
url: https://agentwranglers.se/playbook/website/errors-and-outages/deprecation-and-sunset
id: WEB-226
level: Optional
updated: 2026-10-22
build: a2a6bdfed830
tokens: 729
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Warn before retiring an address

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Errors and outages](https://agentwranglers.se/playbook/website/errors-and-outages.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: WEB-226
- Level: Optional
- Chapter: [Errors and outages](https://agentwranglers.se/playbook/website/errors-and-outages.md)
- Rule: Before you retire an address or API, announce it with `Deprecation` and `Sunset` headers.
- Check: `curl -sI` on the retiring address shows both headers and the link, and the migration notes answer 200.
- 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.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### HTTP 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"
```

## Sources

- [RFC 9745 (The Deprecation HTTP Response Header Field)](https://www.rfc-editor.org/rfc/rfc9745)
- [RFC 8594 (The Sunset HTTP Header Field)](https://www.rfc-editor.org/rfc/rfc8594)

## Related rules

- API-29 [Announce deprecation and sunset in headers](https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers.md) in API design
- API-5 [Keep addresses stable](https://agentwranglers.se/playbook/api-design/resources-and-methods/stable-addresses.md) in API design
- API-28 [Version only for breaking changes](https://agentwranglers.se/playbook/api-design/changes-over-time/versioning.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/website/errors-and-outages/deprecation-and-sunset">Agent Wranglers website playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Hide buttons that need JavaScript until it runs](https://agentwranglers.se/playbook/website/errors-and-outages/hide-script-only-controls.md)
- Next: [Serve the last good page when the server fails](https://agentwranglers.se/playbook/website/errors-and-outages/serve-stale-on-error.md)
- [Errors and outages](https://agentwranglers.se/playbook/website/errors-and-outages.md)