Idempotency Keys Are Not HTTP Caching: Lessons From Wiring Payment Replay
A developer explains why idempotency keys for paid API calls should not be treated as simple HTTP caching. The article describes the payment-identifier extension in @x402/extensions 2.30.0, which maps the same ID and same request to a replayed response, a conflicting request to a 409, and an in-flight request to a 503 with Retry-After. The author found that keying on the router template was flawed, since every route shares that string, and that the key must include the concrete path and a hash of the request body, plus the query string for cached GETs. The piece also recommends returning machine-readable retry guidance in the response body, avoiding replay of sensitive headers like CORS and CSP, and explicitly marking replayed responses. Finally, it advises bounding the cache by TTL, body size, and total entries, noting that the in-flight marker is lost on restart and a persisted replay lock is needed.
This is an AI-generated summary. ShortSingh links to the original source for the complete article.

Discussion (0)
Log in to join the discussion and vote.
Log in