---
title: "Say when to retry · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/errors/retry-after
updated: 2026-10-20
licence: "All rights reserved"
---

# Say when to retry

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

- Level: Required
- Chapter: [Errors](https://agentwranglers.se/playbook/api-design/errors)
- Rule: For 429 and 503, send `Retry-After` so clients know how long to wait.
- How: Give a whole number of seconds, or an HTTP date, as RFC 9110 allows. Seconds are safer, because client clocks drift. Clients wait at least that long before the next try.
- Check: Exceed the rate limit in a test. The 429 answer has `Retry-After` with a whole number of seconds. A forced 503, such as during maintenance mode, carries it too.

**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 api design playbook: https://agentwranglers.se/playbook/api-design/errors/retry-after`.

- Previous: [Hide internals in errors](https://agentwranglers.se/playbook/api-design/errors/no-internal-details)
- [Errors](https://agentwranglers.se/playbook/api-design/errors)