Idempotency

Safe retries on every write operation.

Every write request accepts an Idempotency-Key header. If a request is retried with the same key — after a timeout, a network failure, a crashed process — the original result is returned instead of creating a duplicate.

curl https://api.onzo.la/v1/payments \
  -H "Authorization: Bearer oz_sk_..." \
  -H "Idempotency-Key: 7f9c24e5-1a2b-4c3d-9e8f-6a5b4c3d2e1f" \
  -d '{ ... }'

Rules: - Use a UUID per logical operation, generated when the user intent is created — not per HTTP attempt - Keys are retained for 24 hours - Replaying a key with a different payload returns an error — this protects you from accidental reuse

For money movement, idempotency is not optional hygiene; it is the difference between a retried request and a duplicated payment.