Stripe — idempotency key causes stale response

Stripe returns a stale response because the same idempotency key is reused with different request bodies, so the first response is returned for later calls.

intermediatedebuggingstripeapi

Symptoms

The response does not reflect the updated request body
Two different requests with the same key return identical results
A retry after a parameter change returns the old result

Possible causes

The idempotency key is a static value instead of unique per logical operation
The key is reused after changing the request parameters
The key is generated from a timestamp that collides across retries

Diagnosis steps

Check the idempotency key generation

grep -n "Idempotency-Key" src/api.ts

Interpretation

Confirm the key is unique per logical operation and not reused across different bodies.

Review Stripe idempotency docs

curl https://stripe.com/docs/api/idempotent_requests

Interpretation

Stripe returns the original response for the same key regardless of the new body.

Root cause

Stripe caches the response for each idempotency key; reusing the same key with a different request body returns the cached original response instead of processing the new request.

Fix

Generate a unique idempotency key per logical operation; if the request body changes, use a new key. For retries with the same body, reuse the key to deduplicate.

Verify the fix

Send two requests with different bodies and unique keys; confirm each returns the correct response.

Symptom walkthrough

Stripe returns a stale response because the same idempotency key is reused with different request bodies, so the first response is returned for later calls. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

Stripe caches the response for each idempotency key; reusing the same key with a different request body returns the cached original response instead of processing the new request.

Fix

Generate a unique idempotency key per logical operation; if the request body changes, use a new key. For retries with the same body, reuse the key to deduplicate. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Send two requests with different bodies and unique keys; confirm each returns the correct response. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

grep -n "Idempotency-Key" src/api.ts
curl https://stripe.com/docs/api/idempotent_requests