Idempotency
The network between your server and Hensa can drop after Hensa created a payment request but before you received the response. Retrying without idempotency = two QR codes for one order.
Every request that creates something or touches money (POST) requires:
Idempotency-Key: 6f1c2a9e-0d3b-4c5e-9a7f-2b8e4d6c1a03- Generate one key per intent (e.g. “create the QR for order DH-1024”) – usually a UUID.
- Reuse exactly that key when retrying. A fresh key per attempt defeats the purpose.
- Hensa remembers keys for 24 hours.
What Hensa does
Section titled “What Hensa does”| Situation | Result |
|---|---|
| New key | Processed normally, result stored |
| Same key, same body, within 24 hours | Returns the original result (status code included) – no new record |
| Same key, different body | 409 idempotency_conflict – you’re reusing the key for something else |
| First request still in progress | 409 idempotency_conflict – wait a moment and retry |
Retrying correctly
Section titled “Retrying correctly”Retry with exponential backoff (e.g. 1 s, 2 s, 4 s… up to 5 times) on network errors, 429 or 5xx. Don’t retry other 4xx (400, 401, 422) – fix the request first.