Skip to content
← cd ../posts
[Developer Tools]Updated 4 min read

API Retries: Prevent Duplicate Work With Idempotency

Debug API retries with stable idempotency keys, atomic server claims, bounded backoff, and tests for timeouts that hide successful work.

Quick answer

A timeout does not prove that an operation failed. Reuse one idempotency key for retries of the same logical operation, check the provider’s retention and conflict rules, and bound retries with backoff. The server must prevent concurrent requests from performing the same operation twice.

Repeated request cards pass through a key gate and converge into one completed record.

Your export request times out. You click again, and two export jobs appear. The first request succeeded; only its response was lost. A retry turned an uncertain result into duplicate work.

To debug this class of failure, track the business operation separately from each HTTP attempt. One export can have three attempts and still represent one intended action. This checklist uses a report-export endpoint as a worked example, but the same questions apply to background jobs, uploads, and provisioning workflows.

Start With the Uncertain Outcome

Imagine a POST to /exports. The server creates export exp_42, but the connection closes before the client receives its ID. From the client's perspective, the result is unknown. A timeout is not proof that the server rolled back.

Write down the evidence before retrying: which operation was requested, which attempt failed, and whether a durable record can identify the result. A request log saying “timeout” answers a transport question. It does not answer whether the export exists.

The API debugging checklist helps isolate the failing request. Then add an operation identifier to connect that request with any retries.

Give One Operation One Stable Key

For an API that explicitly supports idempotency, create a key when the user starts a new operation. Save it with the intended payload before sending the request. Reuse both for a retry. Creating a fresh key inside the retry loop makes every attempt look like a new operation.

Here is the identity boundary in JavaScript. This example assumes your own /exports endpoint implements the Idempotency-Key contract; adding a header alone cannot provide deduplication.

javascript
// Create once, then persist this operation before sending it.
const operation = {
  key: crypto.randomUUID(),
  body: JSON.stringify({ reportId: 'report_42', format: 'csv' }),

// Call again with the SAME persisted operation after a retryable failure. async function sendAttempt(operation, signal) { return fetch('/exports', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Idempotency-Key': operation.key, }, body: operation.body, signal, }); } ```

The function intentionally leaves retry policy to its caller. The caller must inspect the HTTP response, decide whether another attempt is allowed, and enforce a deadline. fetch resolving does not itself establish that the application accepted the export.

A page refresh or worker restart should reload the pending operation instead of generating another identity. A user intentionally requesting another export should receive a new key. A UUID generator can help with sample keys during debugging; production code should generate them programmatically.

Make the Server Claim Atomic

For the example endpoint, define a unique database constraint over the authenticated account, operation type, and idempotency key. Store a fingerprint of the validated request alongside the operation state and eventual result ID. Scope matters: an identical key from another account must not expose the first account's result.

Two simultaneous requests must compete for one durable claim. A “find, then insert” check without a unique constraint leaves a race between the two steps. The winner creates the export; the other request follows the endpoint's documented behavior for an in-progress operation. Once complete, repeated requests return the existing export ID.

Keep the claim and export record in the same transaction where possible. If creating the export also enqueues external work, design the handoff explicitly, such as recording an outbox entry in that transaction. A process crash between database commit and queue submission needs a recovery path. A uniqueness check by itself does not make every downstream side effect happen exactly once.

Reject reuse of a key with a different payload. Silently returning the previous CSV export when the caller now asks for a PDF hides a client bug. Define how long records remain available, and reconcile old pending operations before their deduplication window expires.

Read the Provider's Actual Contract

For a concrete provider example, Stripe's API documentation says API v1 retains the first executed request's status and response, including 500 errors, for replay with the same key. It checks for mismatched parameters, and a key reused after pruning can create a new request. Its API v2 behavior differs: retries can continue failed or partially completed work. Check the API version you actually call before assuming a replay will succeed or remain deduplicated indefinitely.

For our export service, write an equally explicit contract: key scope, parameter matching, concurrent-request behavior, result lookup, and retention. A client cannot safely guess those rules from the header name.

Budget Retries Alongside Timeouts

After establishing that an operation can be repeated safely, decide which failures warrant another attempt. A malformed payload needs correction; an expired credential needs the appropriate authentication flow. Rate limits and transient failures need the provider's specific guidance, including Retry-After when applicable. The HTTP status explorer is a useful starting point for interpreting responses.

Amazon's guidance on timeouts, retries, and jitter explains why retries can worsen an overloaded dependency. Use bounded attempts, an overall deadline, and backoff with jitter. Check the SDK's built-in retry policy before adding another loop; independent retry layers multiply traffic.

For an interactive export button, your deadline might end before the job finishes. Preserve its operation key and show a pending state with a status lookup. Do not tell the user the export failed solely because the response deadline expired. For a worker, record the pending operation durably so a restart can reconcile it.

Test the Ambiguous Cases

  • Drop the response after the export record commits. Retrying should resolve to the same export ID.
  • Send two identical requests concurrently. Verify only one durable export is created.
  • Reuse the key with a changed format. Verify the endpoint rejects the mismatch.
  • Restart the client between attempts. Confirm the operation key and payload survive.
  • Simulate a rate limit. Confirm the retry policy respects the server's delay and your overall deadline.
  • Crash between database commit and queue delivery. Verify recovery submits the intended work without creating a second export.
  • Exercise expired keys. Confirm the client reconciles an old operation before risking a fresh creation.

Count business records and downstream work during these tests, not just successful HTTP responses. Two responses can legitimately refer to the same export. One successful response can still hide duplicate worker execution.

Leave a Useful Trace

Log an operation correlation ID, attempt number, elapsed time, response status, and whether the result was newly created or replayed. Keep authentication headers and sensitive request bodies out of logs. Record enough to answer: “Did these three requests represent one export or three?”

The useful end state is a retry path that can explain its decisions. You can identify the intended action, find its durable result, and resume after an uncertain response without inventing a new action.

Sources and further reading

These references explain the standards and APIs discussed in this guide. Check the documentation for the versions and services in your environment.

Related Posts

Useful Tools For This Topic

explore_all →