Stripe: send an Idempotency-Key on every mutating call

TL;DR

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

Steps

1. 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.
2. 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

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

4. Generate the key before the first attempt.
5. On timeout or 5xx, retry with the same key and same parameters.
6. If Stripe returns the same object, it was your retry landing, not a duplicate. Proceed.
7. Only 4xx errors other than rate limits mean "do not retry"; fix the request instead.
8. Read-only GETs do not need keys. There is nothing to duplicate.

When to use

You are seeing this: If your request times out, you retry. Use this skill when you run into "Stripe: send an Idempotency-Key on every mutating call".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Sources

• https://api.stripe.com/v1/payment_intents

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.