article · operations
Prevent duplicate records and recover from failed runs
Prevent repeated actions with stable keys, a durable ledger, atomic claims, bounded retries, and reconciliation when a destination may already have written.
The direct answer
Give each intended action a stable identity and keep a durable record of its state. Before retrying a failed run, determine whether the destination already accepted the action. A timeout means the result may be unknown; it does not prove nothing happened.
A reconciliation example
Synthetic scenario: Intake event I17 should create one reviewed CRM record. The destination creates record H42, but the connection drops before the workflow stores its ID. An operator sees a failed run. Blindly replaying the create step can produce another record.
A safer recovery looks up the approved destination using the same unique external reference, verifies that H42 matches the intended payload, and records completion. If no trustworthy lookup can resolve the outcome, pause for manual reconciliation rather than assume the action failed.
Design an idempotency ledger
Idempotency means repeated attempts at the same intended action do not produce additional effects. A ledger is a stored action record used to track that intent and its outcome.
| Field | Synthetic example | Why it matters |
|---|---|---|
| Action key | intake:I17:create | Stable identity reused across retries. |
| Source version | 3 | Identifies the data a reviewer inspected. |
| Approved payload reference | P17-v3 | Binds execution to the approved content. |
| State | in-progress, then needs-reconciliation | Distinguishes incomplete work from success. |
| Destination ID | H42 once verified | Supports recovery without another create. |
| Attempts and last error | 1; response lost | Explains uncertainty and retry history. |
| Owner and timestamps | Actual operator and event times | Makes unresolved work visible. |
Use states such as pending, in-progress, completed, failed-before-write, and needs-reconciliation. Define transitions so an expired in-progress item does not automatically become permission to create again.
Prevent races, not just repeated clicks
A lookup followed by a separate insert can race: two workers both see no record and both write. Require an atomic claim—a storage operation that accepts only one claim for a key—or a destination operation with a verified uniqueness or idempotency guarantee. A sheet lookup by itself is not proof of concurrency safety.
Keep the event identity distinct from the customer’s identity. Email can change or be shared, and one customer can submit several legitimate requests. Decide whether the action represents a submission, a person, or an update before choosing the key. Do not give each retry a new random key.
Retry rules
Retry a temporary read failure only within an explicit attempt limit and waiting policy. Do not repeatedly retry a permission denial or invalid field; repair the cause first. After a possibly accepted write, reconcile the destination before another write. Use the same action key for the same intent.
If the payload changes after approval, require a new review of that version. A new version does not automatically mean “create a second customer.” Decide whether the business intent is to correct an existing record and use the corresponding reviewed update procedure.
Limits and non-example
“Run once” is a scheduling preference, not a duplicate guarantee. Likewise, a successful workflow log is not enough if the destination state is wrong. Check the external record and preserve evidence of the match.
Exact storage and destination guarantees differ. Keep a design in test mode until simultaneous deliveries, interrupted writes, and recovery have been verified in the selected tools.
Exercise
Trace I17 through failure before write, response loss after write, and replay after completion. Write the permitted next action for each state. If any answer is “retry and hope,” add a reconciliation step and an owner.
Sources and scope
This is an original illustrative recovery design, not a tested connector guarantee. The CRM IDs and ledger entries are synthetic. Verify the chosen storage and destination contracts before implementation.
Next step
Record duplicate and recovery acceptance criteria in the workflow brief. Suggest a correction.
Change notes
Foundation draft prepared October 20, 2026. No public publication or successful live-tool test is claimed.
Next learning step: One-page workflow brief