API header reference
Idempotency-Key header: scope, retention, and payload fingerprints
Design API idempotency keys that prevent duplicate writes without hiding payload changes, tenant collisions, or stale operation results.
An idempotency key identifies one intended operation—not one HTTP attempt. Scope it to the account and endpoint, store a request fingerprint, retain the terminal result for a defined window, and reject the same key with materially different parameters.
Treat the complete response as an evidence record: status, headers, provider code, request identifier, method, and raw body. The sequence below separates what the response proves from the checks still needed before a safe retry or code change.
Diagnostic procedure
Work from evidence to recovery.
- 01
Name one business operation
Generate the key before the first attempt and reuse it for retries of that exact operation.
- 02
Bind it to input
Store a normalized payload fingerprint, tenant, route, and method so accidental key reuse cannot return an unrelated result.
- 03
Define in-flight behavior
Decide whether concurrent duplicates wait, receive conflict, or attach to the original operation.
Idempotency-Key: random UUID regenerated on every retry
One durable operation key + request fingerprint + documented retention and conflict behavior
Duplicate-side-effect riskPOST retries can repeat side effects. Add an idempotency key or a durable operation identifier before enabling automatic retries.
No account · no upload · no endpoint calledOpen the full retry planner and operating notes →
FAQ
Before you ship
Does APITC send this evidence to an API?
No. The matching and calculations in the linked workbench run in the active browser tab.
Should every idempotent request response be retried?
No. Retry behavior depends on the method, idempotency protection, provider instructions, and whether the failure is temporary.
Protocol behavior checked against the Stripe idempotent requests. Recheck your pinned provider/API version before production deployment.