Stripe: send an Idempotency-Key on every mutating call

Stripe: Idempotency-Key on every mutating call

If your request times out, you retry. Without an idempotency key, Stripe sees two requests and can create two charges, two customers, two subscriptions. The fix is one header.

The rule

Send Idempotency-Key with a unique value on every POST that creates or changes something: charges, PaymentIntents, customers, subscriptions, refunds, transfers.

curl https://api.stripe.com/v1/payment_intents   -u [your test secret key]   -H "Idempotency-Key: [a unique value for this operation]"   -d amount=2000   -d currency=usd

Key discipline

• One key per logical operation, not per attempt. Generate the key when the user intent forms (e.g. "charge order 1234"), reuse it across retries of that same intent.
• A UUID v4 per operation is fine. Keying by order ID plus operation name is even better for debugging.
• Never reuse a key for a different operation. Stripe returns the first result for a repeated key, so a reused key silently returns the wrong object.
• Keys expire after 24 hours. That is plenty for retry windows.

Safe retry pattern

1. Generate the key before the first attempt.
2. On timeout or 5xx, retry with the same key and same parameters.
3. If Stripe returns the same object, it was your retry landing, not a duplicate. Proceed.
4. Only 4xx errors other than rate limits mean "do not retry"; fix the request instead.

Read-only GETs do not need keys. There is nothing to duplicate.

Stripe's idempotent requests docs define the Idempotency-Key header for safely retrying requests without performing the same operation twice (docs.stripe.com/api/idempotent_requests). The failure mode is real: a timed-out PaymentIntent create retried without a key can double-charge. Key discipline (one key per logical operation, reuse across retries, never across operations) follows directly from how Stripe scopes keys. Verified against live docs 2026-09-26.