Retry financial commands safely

An uncertain response can occur after the server records money. Idempotency allows a supported command to recognize a retry of the same action instead of creating it twice.

Key format

Send Idempotency-Key on supported financial commands. It allows at most 128 characters, using letters, digits, ., _, : or -.

Idempotency-Key: expense-2026-10-05-unique-reference

This is an illustrative identifier, not a shared key for every request.

Retry sequence

1. Generate a key for one intended action.
2. Save that key with the exact command payload before sending.
3. If the response is lost, retain the same key and identical intent and payload.
4. Inspect the existing result before starting a separate action.
5. Generate a new key only for genuinely new money.

Reusing a key for a different payload is a conflict, not a way to update the old command.

Covered command families

Transaction creation, correction, reversal, restoration, loan recording and settlement money flows use command-specific handling. Currency conversion requires a key. Ordinary setup CRUD is not automatically covered by the same financial receipt contract.

Import recovery

Continue the existing job through its lifecycle action. Creating another upload is not an idempotent retry of the earlier job. If source interpretation changes, review and consent again.

Use errors to handle conflicts and financial safety before exposing writes to a user.