ADR-0005 · Accepted · 2026-08
Why retries require idempotency
Automatic retry without idempotent work creates silent corruption.
Context
Networks fail. Workers die. Schedulers redeliver. If a job posts a payment, writes a row, or sends a customer email, a naive retry duplicates the side effect. Teams then add more status columns and manual cleanup scripts — operational debt that compounds.
Decision
Any job that may retry must be designed for at-least-once delivery: idempotency keys, upserts, deduplication tables, or compensating actions — chosen explicitly per side effect. Retry policy is part of the job definition, not an afterthought in the worker.
Consequences
- Some jobs take longer to design. That is preferred to silent duplicates.
- The execution system can retry aggressively only where the job declares it is safe.
- Operators get a recoverable model instead of a cleanup ritual.