Agent WranglersReliability
Make retries safe with idempotency keys, protect updates with ETags, set timeouts everywhere and tell clients plainly when to slow down.
- Required 3
- Recommended 3
Required
Accept idempotency keys on POST
RequiredLet clients send an
Idempotency-Keyheader on POST and PATCH, and return the first result for a repeated key instead of acting twice.Retry with backoff and jitter
RequiredRetry only safe, idempotent or key-protected requests, and wait longer after each failure, with random jitter.
Set timeouts on every call
RequiredGive every outgoing and incoming request a time limit. Never wait forever on another service.
Recommended
Stop lost updates with ETags
RecommendedSend an
ETagwith every resource, and requireIf-Matchon updates, so one client can't silently overwrite another's change.Tell clients their rate limit
RecommendedLimit requests per client, and tell clients the limit, what is left and when it resets.
Run long jobs asynchronously
RecommendedWhen work can take longer than 10 seconds, accept it with 202 and a status resource the client can poll.
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/reliability.