Documentation
Idempotency
How to retry any request safely, without ever creating a payment twice.
How it works
Every POST request accepts an Idempotency-Key header. The first time VEYRA sees a key, it processes the request and stores the response. If the same key arrives again with the same body, VEYRA returns the stored response instead of performing the operation again.
curl http://localhost:4610/v1/refunds \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: refund-order-1042-1" \
-d '{ "payment_intent": "pi_...", "amount": 2000 }'Rules
| Situation | Result |
|---|---|
| Same key, same body, within 24 hours | The original response is returned. Nothing is executed twice. |
| Same key, different body | 409 idempotency_mismatch |
| Same key while the first request is still running | 409 conflict — retry shortly |
| Key older than 24 hours | Treated as a new key. |
Why this matters
Networks fail after a request has been sent. Without idempotency you cannot know whether a timed-out payment was created. With it, retrying is always safe.
Choosing keys
- Use a value tied to the business operation, such as
order-1042-attempt-1, or a random UUID v4 stored with the operation. - Reuse the key for every retry of the same operation; use a new key for a genuinely new operation.
- Keys can be up to 255 characters.
GETandDELETErequests are naturally idempotent and do not need one.