Idempotency
Every mutating call takes an Idempotency-Key so a retry or a dropped connection never double-creates a task or double-charges escrow.
Networks fail mid-request. Hannu makes that safe: every mutating endpoint requires an Idempotency-Key header, and a replay of the same key returns the original result instead of doing the work twice.
How to use it
Generate a unique key per logical operation — a UUID is ideal — and send it on the write:
POST /v1/tasks
Authorization: Bearer hnu_live_…
Idempotency-Key: 7f3c4e21-9a02-4b8d-b1f0-2c9a51d3e4a7
Content-Type: application/jsonIf you retry with the same key and the same body, you get back the original response — the task is created once. Retrying is always safe.
The rules
- Same key, same body → replayed. The stored response is returned and a replay is flagged, so no second task is created and no second escrow lock happens.
- Same key, different body → conflict. Reusing a key with a changed body returns
idempotency_conflict(409). Use a fresh key for a new request. - Replay window is 24 hours. After that, a key may be reused for a genuinely new operation.
Derive the key from the thing you're trying to create — for example a hash of (order id + step) — so an automatic retry reuses it, but a genuinely new task gets a new one.
Which calls need it
Every POST that changes state: creating tasks and workflows, approving, rejecting, and cancelling. Read-only GETs don't need a key — including POST /v1/wallet/fund, which only reads back your funding options and changes nothing. The API reference marks each idempotent endpoint.