# 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.