---
title: "When things break · Agent Wranglers"
url: https://agentwranglers.se/playbook/website/when-things-break
updated: 2026-10-20
licence: "All rights reserved"
---

# When things break

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

> Plan for things going wrong with error pages, maintenance mode, pages that survive failed scripts, offline support and retired addresses.

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

## Required

- [Make error pages helpful and honest](https://agentwranglers.se/playbook/website/when-things-break/error-pages): Serve 404 and 500 pages with the right status codes and the site's own navigation. Never show stack traces.

## Recommended

- [Say when you'll be back](https://agentwranglers.se/playbook/website/when-things-break/maintenance-pages): During planned maintenance, answer 503 with `Retry-After` and a clear page. Keep the health check working.
- [Keep working when a script or service fails](https://agentwranglers.se/playbook/website/when-things-break/graceful-degradation): When a script, a font or another company's service fails at runtime, the page still shows its content and its main actions still work.
- [Hide buttons that need JavaScript until it runs](https://agentwranglers.se/playbook/website/when-things-break/hide-script-only-controls): Never show a button that does nothing. Hide controls that need JavaScript until the script is running, without moving the page.
- [Let people install the site](https://agentwranglers.se/playbook/website/when-things-break/pwa-manifest): Publish a web app manifest with a name, start address, colours, and 192 and 512 px icons, including a maskable one.
- [Serve the last good page when the server fails](https://agentwranglers.se/playbook/website/when-things-break/serve-stale-on-error): Let caches keep serving the last good copy of a public page for up to a day when the app fails or times out.
- [Collect script errors from visitors' browsers](https://agentwranglers.se/playbook/website/when-things-break/browser-error-reports): Send every uncaught script error and rejected promise from the browser to your own endpoint, and alert when they rise.

## Optional

- [Keep working when the network drops](https://agentwranglers.se/playbook/website/when-things-break/offline-support): Add a service worker, a small script that sits between the page and the network. Show an offline page and cached pages when the network fails.
- [Warn before retiring an address](https://agentwranglers.se/playbook/website/when-things-break/deprecation-and-sunset): Before you retire an address or API, announce it with `Deprecation` and `Sunset` headers.

- Previous: [Privacy](https://agentwranglers.se/playbook/website/privacy)
- Next: [Languages and regions](https://agentwranglers.se/playbook/website/languages-and-regions)
- [All chapters](https://agentwranglers.se/playbook/website)