Separate the request from its effect
In this fictional example, an agent sends CRM update C-28 and the service commits it. The network closes before the reply reaches the agent. The agent now has evidence of a failed exchange, while the CRM has a completed update.
A new request with a new operation identity may repeat an effect that already occurred. Some updates look harmless when repeated; others append activity, emit an event or notify a user. Identify those effects before deciding what may be retried.
| Observation | What it establishes | What remains open |
|---|---|---|
| Agent sees a timeout | The response did not arrive in time | Whether the CRM applied the update |
| CRM receipt names C-28 | The operation can be traced | Whether its recorded result matches the intent |
| Destination record matches | The intended state is observable | Any linked side effects requiring separate checks |
Keep one identity through the investigation
- Retain the original request. Keep its operation ID, target, intended effect and execution time. Protect any sensitive values in the record.
- Query the authoritative system. Prefer its operation-status interface or durable receipt. A fresh read of the object helps, but may not distinguish your update from a concurrent one.
- Use the documented retry contract. Where supported, retry the same logical operation with the original idempotency identity and unchanged meaning. Check retention and scope before relying on deduplication.
- Escalate unresolved ambiguity. If the service cannot establish the outcome, name an owner and preserve the evidence instead of starting an unrelated replacement action.
Define what idempotency does not answer
An idempotency key is useful only within the receiving service's actual contract. Its retention window, request comparison rules and treatment of concurrent calls affect what can be safely repeated. A key in a log does not by itself implement duplicate suppression.
Compensation is also a separate action. Reversing a recorded effect may require permission and its own outcome check. Do not describe a best-effort cleanup as a guaranteed rollback.
For a workflow implementation, Pharos Production's AI automation services provide a relevant starting point for defining integration and exception-handling scope. This note proposes acceptance questions; it reports no measured reliability improvement.
Leave a useful unresolved-operation record
The receiving owner should be able to see the original intent, available receipts, the current unknown and the next permitted action. Write the unknown explicitly. "Needs investigation" without the operation reference sends the next person back to the start.
Operation: C-28
Target: reviewed CRM record
Expected effect: approved field update
Known: request sent; response unavailable
Needed: authoritative outcome for C-28
Owner: named integration responderSources and method
AWS Builders' Library: Making retries safe with idempotent APIs explains caller-provided request identifiers and the limits of guessing intent from equal parameters. C-28 and its handoff template are illustrative additions. Source checked on .