跳到主要内容

Idempotent requests

A timeout leaves the outcome unknown. The request may have charged the card and then lost its response on the way back. Retrying without a key risks a second charge.

The Idempotency-Key header removes that risk. Stripe stores the result of the first request under the key and returns the same result for every retry.

Key mechanics​

  1. The client generates a unique key for one logical operation.
  2. The POST reaches Stripe with the key in the header.
  3. Stripe runs the request and stores the response against the key for 24 hours.
  4. A retry with the same key returns the stored response without running the operation again.

Stripe caches errors as well as successes. If the first request returns a 400, every retry with that key returns the same 400.

Send a key​

curl https://api.stripe.com/v1/payment_intents \
-u "$STRIPE_SECRET_KEY:" \
-H "Idempotency-Key: a1b2c3d4-0001-4f8e-9a1c-7d2e3f4a5b6c" \
-d "amount=2120" \
-d "currency=usd"
Node.js
const key = crypto.randomUUID();

const response = await fetch("https://api.stripe.com/v1/payment_intents", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
"Content-Type": "application/x-www-form-urlencoded",
"Idempotency-Key": key,
},
body: new URLSearchParams({ amount: "2120", currency: "usd" }),
});
Python
import os, uuid, requests

response = requests.post(
"https://api.stripe.com/v1/payment_intents",
auth=(os.environ["STRIPE_SECRET_KEY"], ""),
headers={"Idempotency-Key": str(uuid.uuid4())},
data={"amount": 2120, "currency": "usd"},
)

Choose the key value​

The key must be unique per operation and stable across retries. Any string up to 255 characters works. Most integrations use one of two strategies.

StrategyKey valueTradeoff
GeneratedA universally unique identifier (UUID) created once per operation and passed to the retry layer.Easy to create. The client must persist the key until the operation finishes.
DerivedA stable value such as order-4471-charge-1.Readable in logs. Requires a uniqueness rule you control.
注意

Generate the key once, outside the retry loop. Calling crypto.randomUUID() inside the retry creates a new key per attempt and turns every retry into a fresh request.

Handle the three outcomes​

ResultMeaningAction
Same response, same bodyStripe replayed the stored result.Treat it as a normal success or failure.
409 ConflictA request with this key is still running.Wait, then retry with the same key.
400 with idempotency_errorThe caller reused the key with different parameters.Use a new key for a new operation.

The idempotency_error case points to a bug. The same key arrived with a different amount, currency, or parameter set. Stripe refuses to guess which request the caller meant.

{
"error": {
"message": "Keys for idempotent requests can only be used with the same parameters they were first used with.",
"type": "idempotency_error"
}
}

Set the retention window​

Stripe keeps the result for 24 hours. Three cases need care.

  • Long retries. A queue that retries for more than 24 hours reaches a window with no stored result. The retry then runs as a new request. Cap the retry window below 24 hours, or check the object state before you retry.
  • Delayed reconciliation. A job that replays yesterday's requests hits the same gap. Read the object by ID instead of replaying the write.
  • Key reuse across days. A date-based key such as charge-2026-11-09 collides with tomorrow's retry of the same key. Include the object ID in the key, not the date alone.

Verify the behavior​

Send the same POST twice with one key and one body. The second response returns the same PaymentIntent ID.

KEY=$(uuidgen)

curl -s https://api.stripe.com/v1/payment_intents \
-u "$STRIPE_SECRET_KEY:" \
-H "Idempotency-Key: $KEY" \
-d "amount=2120" -d "currency=usd" | jq -r '.id'

curl -s https://api.stripe.com/v1/payment_intents \
-u "$STRIPE_SECRET_KEY:" \
-H "Idempotency-Key: $KEY" \
-d "amount=2120" -d "currency=usd" | jq -r '.id'

Both commands print the same pi_... value. Now change amount on the second call and keep the key. Stripe returns idempotency_error.

Where to apply it​

Apply a key to every POST that creates or changes money:

  • Creating a PaymentIntent, refund, payout, or subscription.
  • Capturing an authorized charge.
  • Creating a customer when the caller may retry.

Skip the header on GET and DELETE. A GET changes nothing, and a repeated DELETE returns the same result by nature.

Next steps​