A timeout does not mean nothing happened
Imagine a bill-creation request that reaches the ERP, commits a draft and loses its response on the network. Retrying the same business action as a new request can create a second bill. Treating the run as failed can also mislead the operator, because the first record may already exist.
A confirmation flow needs to preserve the operation identity before sending the write, record the available acknowledgment and query the destination for the resulting record. When the destination cannot establish the outcome, the run should remain unresolved rather than guess. Recovery starts with reconciliation, not another model attempt.
Keep request identity and business identity separate
An idempotency key identifies a repeated API submission. A supplier invoice number identifies a business document, usually within a supplier and company scope. These solve related but different problems. Two callers can submit the same invoice using different request keys; one caller can accidentally reuse a key with changed content.
A production adapter needs an explicit strategy for both cases. Use destination-supported idempotency or an enforceable uniqueness boundary where available. Compare the accepted request’s content on replay. Define what happens when a business duplicate is found and avoid assuming that a search followed by a write is atomic.
| Observed condition | Appropriate next step |
|---|---|
| Write rejected before execution | Surface the rejection and its cause |
| Write acknowledged with an identifier | Read back the authorized record |
| Response lost; result unknown | Reconcile using the stable operation identity |
| Existing record differs from the candidate | Hold for an explicit conflict decision |
Confirm the effect the contract actually promised
A draft-creation contract should confirm the draft’s identity, expected fields and relevant status. It should not report payment completion, inventory availability or approval completion unless those are separate verified effects. Multi-step tasks need evidence for each effect and a documented response to partial completion.
Read-back timing and durability guarantees depend on the destination. An adapter must distinguish an accepted asynchronous job from a committed record, and eventual consistency from missing data. Define how long to wait, which observations can establish completion and when an operator should take over reconciliation.
Missing a detail or found a problem?
Send a documentation question →