When Is It Safe to Retry a Failed Document Action?
Reconcile uncertain outcomes before repeating OCR, notifications, or downstream updates
Published
A provider accepts an OCR job, but its response never reaches the caller. The operator sees a timeout and presses Retry. The first job may still finish, leaving two processing bills, competing outputs, or a notification sent twice.
Retry when the outcome is understood, the intended source and parameters still match, and repeating the effect is safe under the integration's rules. If acceptance is uncertain, reconcile the original work first. A failed response alone does not establish that nothing happened.
Make three checks before resubmitting work
- 1 · Outcome
Find what already happened
Inspect platform status, provider jobs, callbacks, and downstream receipts.
- 2 · Intent
Confirm the same work
Match the source version, operation identity, parameters, and destination.
- 3 · Effect
Choose a safe next step
Resume, reconcile, retry within policy, or assign unresolved work to an owner.
Choose between waiting, retrying, and starting a new run
| What you know | Appropriate next step |
|---|---|
| Work is still queued or running | Monitor the original attempt within its expected duration and deadline. Investigate an overdue job before submitting another. |
| A temporary failure is confirmed before any effect occurred | Address the cause, confirm unchanged intent and the full retry scope, then retry within policy. |
| The provider accepted work, but completion is unknown | Query job evidence or reconcile callbacks. Keep the business outcome unresolved until replay is demonstrably safe. |
| The downstream effect already occurred | Reconcile its receipt with the workflow. Repeat delivery only under a verified deduplication contract. |
| Content, parameters, destination, or authorization changed | Revalidate the request and define a new processing run where appropriate. |
| Attempts are exhausted or evidence cannot resolve the outcome | Assign controlled review with an owner, decision record, and next action. |
Separate a confirmed failure from an unknown result
An explicit rejection before a provider accepts work can support a retry after the cause is addressed. A connection timeout after submission leaves the outcome uncertain. Look up the provider job or operation record, and allow for delayed callbacks and status visibility before deciding to submit again.
The Amazon Builders' Library explains why a caller-supplied request identity can distinguish a repeated request from new intent. Apply that identity at the side-effect boundary: two workers must not both pass a duplicate check and then execute the same mutation. Use an atomic claim or a provider's documented idempotency contract, with a recovery path for an interrupted claim.
A checksum identifies content; it does not identify the business operation. Two legitimate submissions can contain identical bytes. Keep the operation identity distinct from the document identity, source checksum, and provider job identifier.
Define how long duplicate-protection records remain valid. A retry arriving after that window needs an explicit recovery decision. Store a fingerprint of the intended parameters alongside the operation identity so reuse with changed content or a different destination can be rejected or reviewed.
Classify the effect you would repeat
| Processing or integration effect | Check before retry |
|---|---|
| OCR, thumbnails, checksums, or extracted text | Confirm the same source and settings. Control which result becomes current and whether repeated processing adds cost. |
| Antivirus or malware inspection | Keep required access restrictions in place until the accepted inspection outcome is available. A processing error is not a clean result. |
| Email, webhook, or event notification | Check delivery evidence and the receiver's deduplication behavior. A lost acknowledgment may follow a completed side effect. |
| Move, publish, delete, or downstream business update | Read current state and recheck authorization and preconditions. Repeating a mutation can change a later version or destination. |
| AI extraction or classification | Track the processing run, model and prompt configuration, cost, and review outcome. Repeated runs can produce different results. |
Available FormKiQ document actions depend on the installed capabilities and selected modules. Keep a separate recovery policy for each configured action rather than applying one rule to every failure.
Bind each result to its intended source
Record the site, document and artifact context, source version or checksum, action type, relevant parameters, workflow step, operation identity, provider job, attempt history, and resulting output. Preserve enough context to explain why a result was accepted.
If the document changes while OCR runs, keep the completion associated with its original source. Mark it stale for the current workflow where appropriate; do not silently attach it as the result for newer content. A changed source, destination, model, or prompt represents new intent and may require a new operation identity.
Work through the lost OCR response
In this illustrative integration, the controller records operation ocr-042 for one source version before submitting provider work. These correlation and acceptance controls are part of the integration design.
Preserve the uncertain outcome
The response times out. Keep the operation unresolved and inspect FormKiQ's action status and the provider's available job evidence. If the original work is still running, wait or reconcile it instead of creating a competing job.
Account for every failed action in scope
Suppose the document also has a failed webhook. Establish whether its receiver already processed the event. Do not invoke the document retry operation solely to recover OCR while that webhook's effect remains uncertain. Resolve the broader scope or use a separately controlled recovery path.
Accept one intended outcome
If the original OCR completes, link its result to the recorded source and deduplicate completion handling. If work is confirmed retryable, preserve the operation context across attempts and apply the agreed retry policy. A later completion must not overwrite a newer accepted result.
Work through a webhook whose acknowledgment is lost
Consider a separate integration that sends a document-approved event to a case system. The application carries stable event identity approval-042 across delivery attempts. The receiver commits its duplicate-protection record and the case update in one database transaction, then sends an acknowledgment. The network drops that acknowledgment.
What the sender sees
Delivery appears to have failed. Before replay, it checks the receiver's event receipt or documented duplicate-delivery behavior. It preserves the same event identity and payload for a retry of the same approval.
What the receiver must do
On repeated delivery of approval-042, it returns the recorded outcome without applying the case update again. A simultaneous duplicate must meet the same atomic check. A reused identity with a changed payload goes to a defined conflict path.
This example depends on controls implemented by the receiver. If it also sends email or calls another service, the database transaction does not cover that additional effect. Give that handoff its own delivery and reconciliation design. A receiver that cannot establish whether it acted leaves the sender with an operational exception to resolve.
Bound retries and keep an accountable exception queue
Use attempt limits, an overall deadline, and backoff with jitter where the caller controls retries. Coordinate client, queue, platform, and provider policies so retries at several layers do not multiply unexpectedly. AWS's retry guidance describes how repeated requests can amplify an overloaded dependency.
Where an integration uses standard SQS queues, design for possible duplicate delivery. A transport message identifier is useful evidence, but the business operation still needs its own identity and duplicate-handling rules.
Map the action statuses supported by the deployed release into an operational view. Separate waiting, running, failed, exhausted, completed, and unresolved business outcomes without inventing new FormKiQ API status values. Assign exhausted or ambiguous work to an owner with the relevant history and authorized recovery options.
Test recovery before enabling automatic replay
- Lose a response after provider acceptance and verify reconciliation finds the original work.
- Inspect multiple failed actions before invoking a document-level retry.
- Deliver duplicate callbacks concurrently and verify one accepted business outcome.
- Change source content during processing and verify the old result cannot replace the current result.
- Exercise receiver deduplication, expired operation records, and unavailable provider status.
- Exhaust the retry budget and verify an owner can review the full attempt history.
Make retry a recorded recovery decision
A safe retry preserves intent while accounting for work that may already have happened. Check the full retry scope, bind outputs to the correct source, and reconcile side effects before replay. When the outcome remains uncertain, keep that uncertainty visible and assign a controlled recovery decision.