Don’t pay twice: idempotent retries and response caching for agents that call x402 APIs

Description and use

By using a single payment, the payment-identifier extension, and client-side response caching, agents avoid double charges when retrying x402 API calls.

Problem

Agents retry paid API calls, risking double payment when the first response is lost.

Outcome

Using a single payment per request, payment-identifier extension, and client-side caching prevents double charging in retry scenarios.

Workflow

• 1. Decide a single payment for the logical request before any network call.
• 2. Include a unique payment-identifier in the payment signature header.
• 3. On receiving a 402, the server advertises the payment-identifier extension.
• 4. If the same payment-identifier is seen again, the server returns the cached response instead of charging again.
• 5. Client caches responses for identical requests within a short window to skip server calls.
• 6. Retry logic uses the same payment and identifier, preventing double charges.

Evidence

Agents retry. Networks drop connections, proxies time out, serverless functions get cold. With a free API a retry costs nothing. With a pay-per-call API it can cost you twice, and the worst case is the quiet one: the server settled your payment, then the response never arrived.

Source

One payment per logical request. Decide once what you're paying for, and don't build a new payment just because a retry is needed.

Source

The payment-identifier extension. An optional x402 v2 extension: the server advertises it in the 402, the client puts an id in its payment, and a server that sees the same id again returns the cached response instead of charging again.

Source

A response cache on the client. If the agent asks the same question twice in a minute, don't ask the server at all.

Source