Back to all articlesIntegration reliability

Handle a timed-out write when you do not know whether it succeeded

Alactic Editorial10 min read

Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.

A record update times out after submission. The operator sees an error, but the receiving system may already have saved the change. Clicking retry could finish the work—or repeat an action that already happened.

Treat this as unknown completion, not confirmed failure. Stop uncontrolled resubmission, preserve the original attempt’s evidence, and check whether the receiving system can establish its outcome. Retry only when documented deduplication protects the same operation, or when an authorised owner has assessed the remaining uncertainty and approved resubmission.

The important question is not simply whether the record now looks right. It is whether the intended business action completed, whether anything happened twice, and what evidence supports closing the case.

1. Separate a failed response from a failed write

A timeout establishes that the caller did not receive completion within its waiting period. By itself, it does not establish where processing stopped. The request might not have arrived, might still be processing, or might have committed before its response was lost.

Use three operational states:

  • Confirmed completion: evidence tied to the intended operation shows that it committed. Any relevant downstream action is checked separately.
  • Confirmed non-completion: authoritative evidence establishes that the operation did not commit and cannot still commit later.
  • Unknown completion: the available evidence does not establish either outcome.

A timeout belongs in the third state unless additional evidence moves it elsewhere. A generic failure message from the calling application is not enough. Neither is an empty search result if the search may lag behind writes.

Likewise, a request receipt proves receipt, not necessarily completion. A queued or accepted state means there may still be work in progress. Before relying on a status response, understand what that state means in the receiving system’s documentation.

2. Freeze the uncertain operation and preserve its identity

Pause retries for the affected operation—not automatically every unrelated write. Check for retries in the client, integration worker, scheduler, and operator workflow. An operator who waits carefully can still be undermined by a worker that resubmits in the background.

Create one incident entry for the uncertain operation. Record:

  • The target system, workspace, record identifier, and intended business change.
  • The submission time and timeout time, including the time zone.
  • The original request or correlation identifier, if available.
  • The supported deduplication identifier, if one was actually sent.
  • A protected reference to the original payload and its version.
  • The last verified record state and any expected downstream action.
  • Known automatic and manual attempts, including attempts whose outcome is also unknown.
  • The person responsible for the next decision.

Keep credentials and unnecessary personal information out of incident notes. Preserve enough information to distinguish this operation from another similar update without copying sensitive payloads into broadly visible channels.

Do not generate a fresh operation identity just to make the error disappear. If the dependency uses that identity to recognise repeats, replacing it can turn a retry into a new action.

3. Choose the strongest available evidence path

Use an operation-status lookup when one exists

Check whether the dependency documents a lookup for the original operation. Do not assume a record lookup is equivalent: operation status answers what happened to a particular attempt; record state answers what is visible now.

If the operation is still processing, wait and recheck according to the documented behaviour. Use bounded checks with a named escalation point rather than an endless polling loop. If a lookup returns no match, establish whether that means definitively absent, temporarily unavailable, expired, or merely not yet visible.

Use supported deduplication only within its contract

Some dependencies provide idempotency keys or another documented mechanism for recognising the same operation. Others do not. A locally generated identifier has no protective effect unless the receiving system supports and uses it for that purpose.

Before a protected retry, verify the identifier’s scope, retention period, payload-matching rules, behaviour during concurrent processing, and the responses returned for repeat attempts. Preserve the original operation and payload as required. If the protection has expired or its conditions are unclear, treat the outcome as uncertain again.

Inspect the record and its history

Without operation-level evidence, inspect the target record, available change history, and relevant downstream records. Look for attribution to the original attempt, not just a matching field value.

A matching value may have been set by another user. An unchanged value may be a stale read. A later edit may have overwritten the original change. Manual verification should document these limitations rather than convert a plausible interpretation into certainty.

4. Filled hypothetical decision table: an uncertain record update

Fictional worked example: an integration submits operation UPD-482 to change record R-731 from Review pending to Review complete and assign it to the onboarding team. The caller times out. In this hypothetical workflow, the transition may also create an onboarding task, so writing the same field values again is not assumed to be harmless.

The following is a filled decision table presented as row cards. Each row is an alternative evidence scenario for the same fictional incident, not a sequence of events. Lookup, history, and deduplication capabilities are conditional examples, not claims about a particular product.

Row A — Completion is established

  • Evidence available: a documented operation lookup reports UPD-482 committed; record history attributes the transition to that operation; one expected onboarding task is present.
  • Duplicate-action risk: resubmission could create an unnecessary second transition or task if repeats are not protected.
  • Safe next step: do not resubmit. Reconcile the caller’s local state with the confirmed result.
  • Owner: integration operator.
  • Closure evidence: saved operation result, linked record history, task reference, and confirmation that queued retries were cancelled.

Row B — Processing has not finished

  • Evidence available: the documented lookup identifies UPD-482 as processing, with no terminal result.
  • Duplicate-action risk: a second submission could overlap with the first.
  • Safe next step: keep the operation paused; schedule the next status check and escalate if it remains unresolved beyond the team’s investigation checkpoint.
  • Owner: integration operator, escalating to the dependency owner.
  • Closure evidence: a terminal outcome followed by reconciliation, or a documented unresolved handoff. A handoff does not count as successful completion.

Row C — Non-completion is established

  • Evidence available: authoritative operation evidence states the request ended without committing and cannot later resume. The record still requires the intended change.
  • Duplicate-action risk: the original attempt cannot duplicate the write, but other actors or changed record state could still make resubmission inappropriate.
  • Safe next step: revalidate the intended change and current permissions, then make one authorised resubmission.
  • Owner: integration operator under the approved recovery procedure.
  • Closure evidence: confirmed result for the resubmission, correct record state, and expected task outcome.

Row D — A documented deduplication control remains valid

  • Evidence available: no terminal result is available, but the original request used a supported key that remains within its documented protection period; the original payload is preserved.
  • Duplicate-action risk: controlled only to the extent specified by the dependency’s documented contract.
  • Safe next step: perform a controlled retry using the same key and matching request under that contract. Do not issue parallel attempts.
  • Owner: integration engineer or authorised operator.
  • Closure evidence: documented terminal response and verification of the relevant record and task outcomes.

Row E — The record matches, but attribution is missing

  • Evidence available: the record shows the desired status and team; no operation lookup or attributable history is available; one task is visible.
  • Duplicate-action risk: unknown. Matching state does not establish which attempt acted or whether another task is pending.
  • Safe next step: avoid replaying an apparently satisfied update. Ask the record owner to verify the business outcome and investigate task ambiguity.
  • Owner: record owner, supported by the integration operator.
  • Closure evidence: verified current business state and task disposition, with original-attempt attribution explicitly recorded as unresolved if it cannot be established.

Row F — There is no authoritative evidence

  • Evidence available: the record appears unchanged, but read freshness is unknown; there is no supported lookup or deduplication control.
  • Duplicate-action risk: unknown and potentially material because the original write might still complete.
  • Safe next step: escalate for manual verification. If waiting would leave unacceptable unfinished work, obtain explicit approval for one controlled resubmission and plan a later duplicate check.
  • Owner: business process owner authorises; integration operator executes.
  • Closure evidence: approval and risk decision, observed result of any resubmission, and subsequent reconciliation of record history and tasks where available.

5. Assess the whole action, not just the field assignment

Setting a field to the same value can appear harmless while the surrounding workflow is not. A write may also append history, create a task, notify a team, or initiate another process. Review what the receiving system actually does before classifying a retry as low risk.

Also distinguish replacement from accumulation. Repeating an assignment may leave the same visible value; repeating an increment or append may change the result again. Neither observation guarantees how a particular API implements the request.

Concurrency creates another failure case. An operator may inspect an unchanged record, then retry just as the original attempt completes or another user edits it. Where the dependency supports version checks or conditional writes, use their documented behaviour to reduce overwrite risk. Such controls do not automatically deduplicate associated side effects.

If the required business change has itself changed during the incident, separate recovery of the original attempt from the newly authorised update. Do not silently alter the payload under an identity intended to represent the original operation.

6. Make authorised resubmission a recorded decision

When evidence cannot resolve the outcome, the choice is between risks: repeating completed work or leaving necessary work unfinished. The operator should not have to make that business decision implicitly by clicking a button.

The decision owner should record what is unknown, the consequence of waiting, the consequence of duplication, and who will reconcile either outcome. Approval should specify whether it covers waiting, manual completion, or a single resubmission—not an open-ended retry loop.

Recovery must still respect access controls. OWASP recommends least privilege and permission checks on every request; an incident is not a reason to borrow elevated credentials or bypass normal authorisation. See its authorization guidance.

Manual completion can also race with the original request. If an operator changes the record directly, include that action in the same incident timeline and check whether the original attempt could still apply later.

7. Close on evidence, then test the next timeout

Close the operational case only when its disposition is explicit: confirmed completion, confirmed non-completion with recovery completed or deliberately cancelled, or an authorised acceptance of remaining uncertainty. Do not relabel an unresolved attempt as a clean failure merely to clear a queue.

If duplication is discovered, stop further retries and identify the authoritative business state. Use an approved corrective process for extra tasks or conflicting updates. Reversing a visible field does not necessarily reverse everything the write triggered.

For the next implementation review, select one write path and run a controlled test in an approved non-production environment: allow the receiving side to process the write while withholding the response from the caller. Check whether operators can identify the original operation, stop retries, find usable evidence, and reach a named decision owner.

Measure the time from timeout to assigned owner, the number of uncontrolled repeat attempts, and whether closure includes evidence for both the record and relevant side effects. The immediate next action is concrete: fill the six decision fields for one uncertain write in your own workflow, and mark every unavailable evidence path before the next incident forces a guess.

API reliabilityTimeoutsIncident handlingCRM operationsIntegration design

Put the next conversation to work.

Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.

Explore Communications