Idempotency
How to retry safely when you do not know whether the first attempt arrived.
Every POST made by the SDK carries an Idempotency-Key, and the same key is kept across the client’s own retries. If a request times out and is retried, we replay the original response instead of doing the work again.
Supply your own when the retry might come from somewhere else — a job runner, a queue, or a customer pressing the button twice:
ts
await sp.paymentIntents.create(params, {
idempotencyKey: `order-${orderId}`,
});The rules
A key is remembered for 24 hours. Replaying it returns the original response, with Idempotent-Replayed: true on the response.
Reusing a key with a different body is an error, not a second payment. That combination almost always means a bug, and quietly doing the new thing under an old key is how a duplicate charge ends up being blamed on us.
Errors are replayed too. If a request failed validation, retrying with the same key returns the same error rather than trying again — the outcome was deterministic and nothing about retrying would change it.