ADR / 007

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.

Reference pattern

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

  1. D01

    A duplicate legal customer is expensive to unwind

  2. D02

    Users need an honest status while the outcome is uncertain

  3. D03

    The receiver can be queried by an external request key

  4. D04

    Transient faults still need retries

03Options considered

Options considered: when each would be the right choice, what it costs, and the verdict under these premises
OptionRight whenCost / trade-offVerdict
Treat a timeout as a failure and retryReceivers that are idempotent by designA duplicate whenever the receiver had committedRejected
Longer timeouts and a manual check before any retryLow volumes, where an operator can check every timeoutUsers wait longer for the same uncertainty; manual checks do not scale and leave no state behindRejected
An Unknown state, resolved by request keyReceivers that are not, or not fully, idempotentNeeds a queryable request key, a resolution job and an ownerSelected

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.

  1. Business state

    Unknown becomes a monitored business state with an age and an owner.

  2. Idempotency

    Retries are safe: the same key cannot create twice.

  3. Reconciliation

    Reconciliation closes the Unknowns that the resolution job cannot.

  4. 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:

01

The receiver guarantees idempotent creation by key.

02

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.

  1. Systems case / 01Designing a CRM–ERP customer lifecycleA premise-led architecture: from commercial intent to a legally valid, operationally recoverable customer.Systems & CRM ArchitectureData & IntegrationsProcess ArchitectureArchitecture case · 18 min

Decisions this one depends on, or constrains.

  1. ADR / 001Make ERP customer creation asynchronousProtect the commercial workflow from ERP latency while making pending state and recovery explicit.Proposed patternIntegration · ERP · Resilience
  2. 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.Proposed patternIntegration · Data · Governance
  3. ADR / 003Use code at orchestration boundariesKeep transparent local rules declarative; move stateful, cross-system orchestration behind tested service boundaries.Proposed patternAutomation · Governance · Integration