[The agent fieldbook](https://www.agentlist.io/learn/guides) # Before an agent retries a write, find out what happened Handle ambiguous timeouts with operation records, provider-supported idempotency, and reconciliation before repeating an external write. Supplemental guide4 min readPublished October 22, 2026Updated October 23, 2026 A timeout can leave an agent with an awkward problem: the remote service might have completed the action even though the response never arrived. Repeating the action could create a second ticket, send another message, or submit the same order twice. The recovery path needs to answer whether the intended operation already happened. This guide proposes a procedure for teams building agent integrations. Test it with a sandbox service and disposable records, not real customer actions. ## Give the operation an identity Before submitting a write, persist an application operation ID, the provider idempotency key where supported, the destination account and API endpoint, and the original request parameters. Recovery must reuse the stored key and parameters, including after a worker restart. Keep sensitive payloads in an appropriately protected store. Logs can reference that record without copying it. Use one operation identity for one intended action. An attempt is a request to perform that action. Several attempts can belong to the same operation. For example, “create the draft ticket for incident 417” is one operation. A network retry is another attempt at that operation. A later decision to create a separate follow-up ticket is new work and needs a new identity. ## Check the provider's retry contract Some APIs accept an idempotency key. [Stripe's API documentation](https://docs.stripe.com/api/idempotent_requests) shows an `Idempotency-Key` header on a creation request. That is a provider-specific contract, not a capability to assume for every tool an agent can call. Before using any provider's mechanism, check which endpoints support it, how long keys remain meaningful, which parameters must remain identical, and what happens after errors. Confirm that your connector actually forwards the key. Adding a field to the agent's prompt does not make the remote service enforce it. Even one provider can have different contracts. Stripe's [error-handling guidance](https://docs.stripe.com/error-low-level) treats a `500` response as indeterminate: the operation might have produced side effects. API v1 caches that response, so a same-key retry can return the same error. Do not switch to a new key while the original outcome is unknown. Reconcile through the affected object, request logs, or webhook events. API v1 keys can be pruned after they are at least 24 hours old; reusing a pruned key creates a new request. If the result is still unknown at 24 hours, stop retries and reconcile it before another write. Stripe's [API v2 contract](https://docs.stripe.com/api-v2-overview#idempotency) differs: requests with the same key, to the same API, within the same account or sandbox and within 30 days qualify as idempotent replays. A replay avoids repeating successful operations and re-executes failed or partially failed work without duplicate effects, returning an updated response. If replay cannot succeed, it returns an error. Identify the API namespace before choosing the recovery path. If there is no supported deduplication mechanism, decide how to reconcile an uncertain result before enabling automatic retries. ## Preserve uncertainty after a timeout Record an unknown outcome as unknown. Do not silently convert it to failed or completed. Where the API supports a safe retry under the same key and parameters, follow that contract. Otherwise, inspect the destination using a reliable operation reference. A search by title alone can confuse two legitimate records with the same name. If the service offers neither safe retry semantics nor a reliable lookup, stop that operation for reconciliation. Report the destination, attempt time, and uncertainty. A generic instruction to “try harder” cannot supply missing transaction semantics. ## Test the lost-response case Use a controlled test harness that can discard a response after the sandbox service accepts a write: 1. Create one operation record and submit its first attempt. 2. Discard the response at the test boundary. 3. Run the configured recovery path. 4. Inspect the destination and count the resulting objects. 5. Check that the local operation record matches the remote result. The expected result is one intended object and an accurate final status. If two objects appear, keep automatic retries disabled for that path until you understand where deduplication failed. Also test a genuinely rejected request. Recovery must distinguish an action that did not execute from an action whose result is unknown. Put the recovery decision in the integration code and runbook. The agent can explain the state and collect missing information; it should not have to improvise the rules for every timeout. For the surrounding workflow, read [Turn one good result into a workflow you can trust](https://www.agentlist.io/learn/guides/build-a-repeatable-workflow). Use [Connect the right tools](https://www.agentlist.io/learn/guides/connect-agent-tools) to map operations and destinations before implementing recovery. For duplicate detection, prefer a stable operation reference over a title search. Sources checked October 23, 2026. Test the recovery procedure against the API namespace and connector you use. --- Source: [Before an agent retries a write, find out what happened | agentlist.io](https://www.agentlist.io/learn/guides/retry-agent-writes). This is the public page rendered as Markdown; interactive controls require the website.