Expiry, Partial Failures and Recovery Points

Expire keys after the documented window (Stripe uses 24 hours) with a cleanup job or TTL. The hardest case: an operation with several steps (create order → charge card → send email) crashed halfway. Model recovery points (atomic phases) and store which phase completed; a retry with the same key resumes from the last recovery point instead of starting over. Each external call uses its own derived idempotency key ({key}:charge) so repeating a phase is safe.

Recovery-point design

key = 01J9ZQ…
phase 1 (DB tx): create order (status=pending), record recovery_point='order_created'
phase 2: charge card with provider Idempotency-Key '01J9ZQ…:charge'
         → record recovery_point='charged', payment_id
phase 3 (DB tx): mark order paid, enqueue receipt email (outbox), recovery_point='finished', store response
Retry after crash in phase 2 → reads recovery_point='order_created' → repeats phase 2 with the same derived key
(provider dedupes the charge) → continues to phase 3.

Common pitfalls

• Keys expiring before clients stop retrying.
• Re-running all steps on retry (double side effects).
• No alerting on keys stuck in 'processing'.

Key points

• Documented expiry window
• Recovery points for multi-step operations
• Derived keys for downstream calls

Further reading: Brandur: idempotency keys and recovery points