Documented incidentPublished 2017-02-22StripeEngineering design article

Design reference: idempotency keys make retried payment API calls safe (Stripe)

Stripe explains that a client which cannot tell whether a request succeeded (for example after a network failure) needs to retry safely, and that without protection a retried charge could double-charge a customer.

What happened

  • The article describes idempotency keys, where the server stores the result of the first request under the key and returns it for retries.Designing robust and predictable APIs with idempotency

The failure pattern

Duplicate action after an ambiguous resultA request times out, the caller assumes it failed and retries, and the money moves (or the order ships) twice.How to prevent it
Watch the pattern: Duplicate action after an ambiguous result

Safeguards that address it

CollectSEA's engineering analysis of what would have prevented or contained this failure.

  • Attach idempotency keys to state-changing requestsStore the result of the first request under the key and return it for retries so a retried charge is never applied twice.
  • Treat timeouts as unknown, not failedReconcile with the server before repeating an operation whose outcome is unknown.

Related standards

CollectSEA's mapping through this incident's failure pattern; not an official determination by the standards bodies.

Building something similar?

Describe your design and see every precedent that applies, with safeguards you can hand to your coding agent.

Analyze your design

Incidents with the same pattern