Docs › Core concepts › Idempotency

Idempotency

Retry a request safely without charging a customer twice. Every write endpoint accepts an idempotency key, and we keep the result for 24 hours.

Sending a key

Pass a unique value in the Idempotency-Key header. Generate it on your side before the first attempt, and reuse the same value for every retry of that same logical operation — not for a new one.

curlnodepython

# the same key on every retry of this one payment
curl https://api.example.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: pay_2026-09-02_a41f9c" \
  -d amount=4500 \
  -d currency=myr

Do not reuse a key across different payloads

If the same key arrives with a different body, the request is rejected with idempotency_key_reuse rather than silently returning the old result.

What gets stored

Field	Kept for	Notes
`status_code`	24 hours	Replayed exactly, including 4xx
`response_body`	24 hours	Byte-for-byte the first response
`request_hash`	24 hours	Used to detect a changed payload

After 24 hours the key expires and the same value may be used again. In practice this means a retry queue that runs longer than a day needs to treat expiry as a real case, not an edge one.

Last updated 28 August 2026Was this page helpful? Yes / No