Treat uncertain integration outcomes as unknown, not failed
A timeout says nothing about whether the receiver committed. Model ‘unknown’ as its own state, resolve it by request key, and only then retry or fail.
Independently created. Contains no employer or client implementation detail, internal names or figures.
01Context
A CRM sends customer-creation and order requests to an ERP through an integration layer. Under load, some calls time out after the ERP has already committed. The integration marks them failed; users or automated retries resend, and duplicate legal customers and orders appear. Other timeouts really are failures—and to the caller the two look identical.
02Decision drivers
- D01
A duplicate legal customer is expensive to unwind
- D02
Users need an honest status while the outcome is uncertain
- D03
The receiver can be queried by an external request key
- D04
Transient faults still need retries
03Options considered
| Option | Right when | Cost / trade-off | Verdict |
|---|---|---|---|
| Treat a timeout as a failure and retry | Receivers that are idempotent by design | A duplicate whenever the receiver had committed | Rejected |
| Longer timeouts and a manual check before any retry | Low volumes, where an operator can check every timeout | Users wait longer for the same uncertainty; manual checks do not scale and leave no state behind | Rejected |
| An Unknown state, resolved by request key | Receivers that are not, or not fully, idempotent | Needs a queryable request key, a resolution job and an owner | Selected |
Every option is right under some premises. The verdict applies to the context above.
04Decision
Every outbound request carries an idempotency key scoped to the business request and a correlation ID. A timeout or lost response moves the request to Unknown—not Failed. Before any retry, the integration layer looks the request up at the receiver by its key: found means confirm; not found means retry with the same key; still unresolved after the retry budget means escalate to a named owner. Users see “outcome being confirmed”, never an invitation to press the button again.
05Consequences
What this choice changes elsewhere in the system.
- Business state
Unknown becomes a monitored business state with an age and an owner.
- Idempotency
Retries are safe: the same key cannot create twice.
- Reconciliation
Reconciliation closes the Unknowns that the resolution job cannot.
- Integration contract
The receiver must support lookup by external request key—or the integration layer keeps a ledger of what it sent.
06Revisit when
The decision holds while its context holds. Challenge it when:
The receiver guarantees idempotent creation by key.
The operation becomes read-only or naturally idempotent.
07Where this decision is applied
The decision says why this path was chosen; each case shows how it takes part in a larger architecture.
08Related decisions
Decisions this one depends on, or constrains.
- ADR / 001Make ERP customer creation asynchronousProtect the commercial workflow from ERP latency while making pending state and recovery explicit.
- ADR / 008Run reconciliation as a permanent control, not an exception processDelivery guarantees fail silently. A scheduled comparison of expected and actual populations—with an owner for every kind of difference—is part of the architecture, not cleanup.
- ADR / 003Use code at orchestration boundariesKeep transparent local rules declarative; move stateful, cross-system orchestration behind tested service boundaries.