Agent WranglersWhen things break
Plan for things going wrong with error pages, maintenance mode, pages that survive failed scripts, offline support and retired addresses.
- Required 1
- Recommended 6
- Optional 2
Required
Make error pages helpful and honest
RequiredServe 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
RecommendedDuring planned maintenance, answer 503 with
Retry-Afterand a clear page. Keep the health check working.Keep working when a script or service fails
RecommendedWhen 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
RecommendedNever 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
RecommendedPublish 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
RecommendedLet 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
RecommendedSend 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
OptionalAdd 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
OptionalBefore you retire an address or API, announce it with
DeprecationandSunsetheaders.
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.