After an API timeout, only write again once you have checked whether the first command reached the destination system. A timeout means your application received no final response; it does not mean AFAS, a carrier or a payment provider did nothing. Retrying blindly can cause precisely the duplicate entry that a retry was supposed to resolve.
Uncertain is a process status of its own
There are three fundamentally different outcomes: confirmed failure, confirmed success and uncertainty. Only the first is immediately suitable for a normal retry. With an uncertain write, the server may have processed the command before losing the connection. Explicitly mark that attempt as “check outcome” and block dependent follow-up actions until the facts have been established.
Before the POST, record what you will write: workspace, order, action, deterministic reference and a limited hash or snapshot of the business content. This recording point matters. If the process crashes after sending but before saving the response, the recovery process still knows which external identity to search for.
Runbook: evidence before retry
- Pause automatic retries. Prevent several workers from handling the same uncertainty simultaneously.
- Search by deterministic identity. Use a unique order reference, posting key or provider ID; do not match on amount and date alone.
- Compare the contents. A record with the same key but different lines is a conflict, not a success.
- Record the evidence. Record which source confirmed whether the command exists.
- Choose one next step. Link the existing record, resubmit safely or investigate manually.
This develops the general principle of idempotency in concrete terms. In a WooCommerce–AFAS integration the business reference, in particular, must remain recognisable throughout the process.
Fictional example: response lost after a posting
Fictional example: homeware store Lumenhuis sends a financial posting with reference LH-2026-00918 to AFAS. The connection drops after thirty seconds. The client sees a timeout, but AFAS has already saved the posting. Its status becomes “uncertain”; the next automatic attempt remains blocked.
A recovery step asks AFAS specifically for LH-2026-00918. The record exists and its lines, amount and debtor match the snapshot saved in advance. The integration links the external identity to the original attempt and marks it complete. There is no second POST. If no record had been found and the search itself had completed reliably, one controlled retry could have been released. This example is fictional; the key is not to interpret the technical absence of a response as the business absence of a record.
Design choices that make recovery possible
| Choice | Why it is needed |
|---|---|
| Deterministic external reference | Enables a targeted receipt check |
| Recording before sending | Survives a crash between request and response |
| Locking per substep | Prevents competing recovery attempts |
| Content comparison | Prevents linking to a coincidentally similar record |
| Visible uncertainty | Gives operations a different action from a normal error |
Connect can model these provider steps with a status and audit trail. In Desk the employee can then see whether a record is confirmed, still under investigation or safe to resubmit. Avoid telling customers “the posting failed” while its outcome is actually uncertain.
Practise the runbook with artificial failures. Break the connection once before the provider receives the request, once during processing and once after the destination record has been created but before the response returns. Those three cases may look the same to the client, but require different recovery decisions. Check whether the system retrieves the previously saved intent after restarting and whether locking stops two recovery workers from acting simultaneously. Do not give manual operators an unrestricted “send again” button without first showing the verification result. When a provider offers no reliable search facility, the process must become more conservative: longer observation, explicit human checks or a unique reference in a report that becomes available later. Hiding uncertainty behind a technical retry policy does not remove it.
For each provider, record which read route counts as sufficient evidence and how long it takes for data to appear there. An immediate search may find nothing because indexing is delayed. In that case, “not found” is not final either, and a second, delayed check belongs before the retry.
Want to make retries safe for your financial or logistics APIs? Work through one uncertain-write scenario with Yindle.