Where the header is required
GET requests ignore the header.
A required key that is missing returns 400 validation_idempotency_key_required. A key longer than 255 characters returns 400 validation_idempotency_key_invalid.
How a key behaves
Keys are scoped to your account. Two businesses can use the same key value without touching each other.1
First request
Payve runs the request and remembers the response for 24 hours.
2
Same key, same request, after it finished
Payve returns the stored response with the original status code, and adds the header
Idempotent-Replayed: true. Nothing runs again.3
Same key, while the first is still running
Payve returns
409 idempotency_conflict. Wait a moment and send the same request with the same
key.4
Same key, different endpoint or different body
Payve returns
422 idempotency_key_reused. The first request stands. This one is refused.409: a request with this key is in flight
422: the key was used for something else
details.differs is body or route. The body comparison ignores the order of JSON keys, so reordering fields is not a different request. Changing any value is.
What is and is not remembered
- Successful responses are remembered for 24 hours.
- Failed requests are not. If a request ends in an error, the key is released and you can retry with the same key.
- Payouts, pay-ins and conversions are also de-duplicated permanently on your account and key. Sending a key you used for a payout last month returns that payout, not a new one.
The 24-hour window is how long a replay returns the stored response and how long a changed body is
detected. It is not how long a key stays unique for a payout. Never recycle keys.
Choose a good key
Use a random UUID, or derive the key from your own record, such aspayout-<your order id>.
When to retry
Cautions
Do not generate the key inside the retry loop
Do not generate the key inside the retry loop
A key created on each attempt is a different key each time. Create it once, outside the loop,
and store it.
Do not reuse a key after changing the amount or the recipient
Do not reuse a key after changing the amount or the recipient
A changed body under an old key is refused with
422. A new payout needs a new key.Do not use a timestamp as the key
Do not use a timestamp as the key
Two attempts made at different times produce two keys, and two payouts.
A bulk payout key covers the whole batch
A bulk payout key covers the whole batch
Replaying a bulk request with the same key returns the first response and creates nothing new.
See Bulk payouts.
Idempotency on your side matters too
Idempotency on your side matters too
Payve delivers webhooks at least once. Record each event id so your own handler does its work
once. See Handle events safely.

