---
topic: system-design
author: Crashtech Editorial
published: Nov 13, 2026 · read: 5 min
---

A Timed-Out Payment Is the Hardest Request to Retry

HTTP cannot tell a client whether a timed-out POST took effect. Idempotency keys, durable results and bounded retry policies make recovery safer.

– –

The card terminal freezes after a customer taps to pay. The cashier sees no approval, so the natural move is to tap again. But the first request may have reached the processor and its reply may be the part that was lost. A timeout is evidence of uncertainty, not evidence that nothing happened.

That small distinction separates a resilient retry from a duplicate charge. It appears in payment APIs, order creation, job submission, email sending and any endpoint where repeating a request can create a second effect.

Idempotency is about the intended effect

HTTP defines an idempotent method as one whose intended effect is unchanged when an identical request is repeated. A client can generally retry an idempotent request when a connection fails before the response is read. The standard warns against automatically retrying non-idempotent requests unless the client knows the operation is safe or can determine that the original was never applied. A generic HTTP client usually cannot know that from a timeout alone. RFC 9110

This is why “retry on network error” is incomplete advice. A network error describes the communication path. It does not reveal which side effects occurred behind the server boundary.

For a create-payment request, the application can add an idempotency key: a client-generated identifier that names one logical attempt. The client reuses that key when it retries the same attempt. The server stores the key with the result and returns that result again rather than creating another payment. Stripe documents this pattern for its API, including parameter comparison and retention behavior. Those details are a service contract, not a universal HTTP feature. Stripe API documentation

The server needs a durable decision record

A key only works if its lifecycle is explicit. A robust design defines at least four things:

  1. Scope: Is the key unique per account, endpoint, operation type or globally? Scope it so unrelated callers cannot collide or inspect each other’s result.
  2. Request identity: Store a canonical request fingerprint alongside the key. If the same key arrives with different parameters, reject it clearly; do not return an unrelated old response.
  3. Atomicity: The key claim and business operation need a transaction or equivalent coordination. Otherwise two concurrent copies can both pass a “not seen” check and both create the effect.
  4. Retention: Keep the record longer than the documented retry window and the maximum realistic client recovery delay. After expiry, a late retry may become a new operation, so clients need a deadline and an explicit way to check status.

A useful record might contain the key, tenant, operation type, request hash, state, result reference, and creation/expiry timestamps. The state often needs to distinguish “in progress” from “completed.” A duplicate request that arrives while the first is still running should not race past it; the server can wait briefly, return a retryable status, or provide a status resource, depending on its API contract.

The exact response policy varies. Some services cache completed responses; others store a result reference. Errors also need deliberate treatment: was the request rejected before execution, or did execution begin and fail ambiguously? Clients should follow the provider’s documented behavior rather than assume all error responses are replayed the same way.

Retries need a budget

Even a safely deduplicated request can overload a struggling service. Use bounded exponential backoff with jitter so a large group of clients does not retry in lockstep. AWS’s engineering guidance explains why synchronized retries can amplify an outage and why retries at multiple layers multiply load. AWS Builders’ Library

Set a total attempt or time budget. Honor a server-provided Retry-After value where applicable. Retry only documented transient failures; a permission denial, malformed request or business-rule rejection usually needs a changed request or user action. Avoid stacking independent retry loops in a browser, SDK, gateway and worker without considering their combined limit.

For consequential work, expose a status check keyed to the logical operation. If the connection breaks, the UI can say “checking whether this payment completed” rather than inviting an immediate second charge. The back end can resolve the existing operation before offering a new attempt.

For systems that retry through multiple layers, see Crashtech’s guide to token-bucket rate limiting and the discussion of why teams build API gateways. A rate limiter can contain retry pressure, but it cannot make a duplicated business operation safe; that guarantee still belongs with the operation owner.

A practical review checklist

Before adding retries to a write endpoint, ask:

  • Can repeating this request create another charge, order, message or job?
  • Is the operation identifier stable across the client’s retries?
  • Does the server atomically associate that identifier with one result?
  • What happens when the same identifier arrives with changed parameters?
  • How long are results retained, and what happens after expiry?
  • Which failures are retryable, and what is the total retry budget?
  • Can a user or client query the state of an uncertain operation?

The most important design choice is not how many times a client retries. It is whether the system can recognize the same intent after the reply is lost. Build that recognition at the server boundary, then let clients retry within the contract.

A pharmacist pauses before retrying a payment on a terminal after a network interruption.
Conceptual illustration of an uncertain payment retry; it does not depict a real transaction or payment interface.
Advertisement

Frequently asked questions

Why can a client not safely retry every timed-out POST?

A timeout reports that the client did not receive a response, not that the server did no work. The server may have completed the operation and lost the reply. Repeating a non-idempotent request can therefore create a second payment, order or job unless the application has a duplicate-detection mechanism.

What does an idempotency key do?

It gives one logical operation a stable identifier. The server stores that identifier with the operation result and returns the same outcome when the same request is repeated. The key must be scoped, retained long enough for retries and checked against request parameters so it cannot silently refer to different work.

Should a client retry every error with the same key?

No. Retry only failures the service documents as transient, use bounded exponential backoff with jitter, honor Retry-After when supplied, and stop at an operation deadline. Validation and permission failures need correction, not repetition; a reused key must not turn a new intent into an old operation.

Sources & further reading

/* Comments */