Browse documentation
Handle uncertain external outcomes
Use request identity and provider contracts to resolve ambiguous results.
A timeout does not tell you whether a provider acted. Model an uncertain outcome explicitly and resolve it through the adapter’s delivery contract.
1. Classify the operation
Determine whether it is read-only, safely repeatable, deduplicated by the provider or dependent on reconciliation. A retryable transport error does not make a business action safe to repeat.
2. Retain the action’s identity
If the provider supports idempotency, retain one stable key for the business action. Retry with that key and compatible content. Follow the provider’s retention and conflict rules.
Changing the key on each retry can duplicate the action. Reusing it for different actions can conceal a conflict.
3. Represent uncertainty
Conceptual states, not API syntax:
Requested
├── confirmed success ──▶ Completed
├── confirmed refusal ─▶ Refused
└── ambiguous result ──▶ Needs reconciliation
├── query existing outcome
├── retry under provider contract
└── request operator decision
Retain enough request identity and context to resolve the outcome. Do not treat no response as a confirmed refusal.
4. Define the adapter boundary
Specify typed inputs and results, limits, authentication, destinations and authority. Keep credentials in the host’s supported secret mechanism. Native process permissions remain part of the trusted boundary.
5. Test the ambiguous interval
Test after provider acceptance but before a usable response reaches the caller. Confirm that reopening preserves the business identity and scope.
Also test duplicates, conflicting payloads, permission withdrawal and reconciliation results that disagree with local assumptions. Scripted answers test decision logic; the real adapter needs separate validation.
Describe the actual guarantee—deduplication, recorded result or reconciliation state. Durability does not imply universal exactly-once external delivery.