request_id on a retry and the gateway returns the original payment or quote-request batch, with its current status, instead of creating a second one.
This page is the API reference. How the key is scoped, what to do for each status, and how retries work over x402 and MPP are in the Idempotency guide.
The key: request_id
You choose the value. A stable, unique-per-operation string works best (an order id, or a UUID if you already mint them). Store it before you send the request — it’s the only thing that links a retry to its original.
Supported endpoints
Idempotency applies to state-changing (POST) endpoints. Each has its own key: reusing one across the two does not carry over.
GET reads (/status, /resolve, /timeline) have no side effects, so there is nothing to deduplicate.
Detecting a replay
Every successful write response carriesidempotent_replay:
true— you were handed a resource that already existed; nothing new was created or charged.false— this request created it.
Different terms and errors
Reusing arequest_id with different economics (source, destination, fulfillment_amount, max_source_amount) is refused with 409 IDEMPOTENCY_TERMS_MISMATCH. Deadlines and the signature may change on a retry. Which errors let you reuse the key: When a request is refused.
Example
sender_auth signature — there is no API key. Re-send the exact same request, with the same request_id, to recover the original result after a timeout or crash; the response’s idempotent_replay tells you whether it was created now or already existed.