Handle an uncertain external outcome

An external request times out. Did the provider reject it, accept it, or act before the response was lost? Treat that uncertainty as part of the operation’s contract.

This guide is a design procedure for an integration. Provider-specific code and guarantees belong to the adapter you actually use.

1. Classify the operation

Ask whether the operation only reads, can safely be repeated, supports an idempotency key, or requires reconciliation after an ambiguous result. “Retryable” must refer to an operation and provider contract, not merely to an HTTP error code.

For example, charging a payment twice may be unacceptable even if both requests are syntactically valid. Reading its status can be the correct next step after an uncertain charge.

2. Give one business action one identity

When the provider supports idempotency, derive or assign a stable identity for the intended action and retain it with durable progress. Retries of that action should use the same identity and compatible request content.

A new attempt identifier for every network retry defeats deduplication. Reusing one identity for different business actions is equally wrong. Follow the provider’s retention period and conflict rules.

3. Represent uncertainty explicitly

This conceptual state sketch is not a Septa API declaration:

Requested
  ├── confirmed success ──▶ Completed
  ├── confirmed refusal ─▶ Refused
  └── ambiguous result ──▶ Needs reconciliation
                              ├── query existing outcome
                              ├── retry under provider contract
                              └── request operator decision

Keep “no response” distinct from “the provider refused.” A durable record should preserve enough identity and context to resolve the ambiguity without guessing.

4. Keep the boundary explicit

Define typed request and result values, limits, authentication, allowed destinations and the authority required by the integration. Keep sensitive credentials in the host or adapter’s supported secret mechanism.

The native component’s operating-system authority belongs in the trust model. The managed core’s effect declaration does not sandbox the native process.

5. Test the ambiguous interval

Exercise the interval after provider acceptance and before the local caller receives a usable result. Confirm that reopening does not create a different business action or bypass the intended scope.

Also test duplicate requests, conflicting payloads under one identity, permission withdrawal and a reconciliation response that disagrees with local assumptions.

Scripted effect answers are useful for testing decision logic. Validate the real adapter and provider behaviour separately.

6. State the actual guarantee

Describe the outcome in terms the integration establishes: retained request identity, deduplicated provider action, recorded result or an explicit reconciliation state. Durable execution does not imply universal exactly-once external delivery.