A slow connection does not tell a user whether an action failed. The server might have created the order before its reply disappeared. When commissioning an API integration, ask what happens after the same request arrives again, not only what happens on the first successful attempt.
Related service: Custom software development- 01Create an identity for the intended action.
- 02Validate the request and permissions.
- 03Record the outcome against that identity.
- 04Return the known result on a repeat.
- 05Investigate unresolved outcomes before restarting.
SECTION 01
Ask what the repeat-request contract promises
Idempotency means that repeating the same operation does not multiply its intended effect. It is a contract with boundaries: the operation it covers, how long its record is retained, which account owns it and what happens if the input changes. Disabling a submit button alone cannot cover network retries or two devices.
Stripe documents one concrete implementation of request keys; its behavior varies by API version. Azure's retry guidance explains why a timeout after a successful write can produce duplication. Ask the agency to document the actual connected provider's rules rather than promise permanent, universal exactly-once processing from a randomly generated key.
SECTION 02
Illustrative example: one purchase request, two attempts
Imagine a staff member submits a purchase request for six monitors. The connection drops while the approval request is being created. They press retry. Both attempts should refer to the same intended request and lead to the existing approval item, not two purchasing commitments. This is a hypothetical acceptance scenario.
If they change six monitors to eight, silently reusing the original identity is also wrong. The interface should explain that the first request exists and offer an authorized amendment or a clearly new request. Retain enough context to distinguish a changed intention from retransmission, without recording unnecessary sensitive details in diagnostic logs.
SECTION 03
Test the awkward interval after the write
For an initial integration, focus on important create or submit operations. Read-only calls may not need a custom record of every request. An existing platform's built-in protection can be preferable if its retention, concurrency and lookup behavior fit the workflow. The proposal should identify what remains outside that protection.
Ask for a demonstration that interrupts the response after the business record is saved, then retries with the same identity. Repeat concurrently, change the payload, switch accounts and retry after the documented retention window. Confirm the number of resulting records and downstream notifications. Include a support path for an uncertain provider outcome; blindly assigning a fresh identity may turn a recoverable timeout into a real duplicate.
SECTION 04
Frequently asked questions
Should every retry receive a new key?
Not when it repeats the same intended action. Preserve its identity; use a new identity only for a genuinely new action under the agreed contract.
Does this eliminate every duplicate?
No. Protection depends on retention, participating systems and downstream behavior. Reconciliation and support checks are still useful where outcomes can remain uncertain.
What belongs in the agency quote?
Include request identity rules, provider-specific behavior, concurrency tests, outcome lookup and an operator recovery path, not merely an extra request header.
PRIMARY REFERENCES
Sources and further reading
These references cover the standards, platforms, or published prices discussed in the guide. Worked examples and checklists are our editorial guidance.
- Idempotent API requestsStripe Documentation
- Retry pattern and failure handlingMicrosoft Learn
EDITORIAL METHOD
About this guide
We use AI to assist with drafting and editing. Catapult AI Work is responsible for the published content. Examples illustrate possible approaches; they are not client case studies unless identified as such.
Budget examples are not Catapult package prices. Check linked provider pages for current fees and plan limits before making a purchase.
Read the editorial policy