A key aspect of Midaz’s reliability is making sure operations are safe to retry and never processed more than once. Whether you're handling transactions or creating new entities, your requests should be resilient — and free of duplicates.
This guide covers how Midaz supports retries through idempotency keys, and how it protects the uniqueness of critical entities like Accounts and Ledgers.
Retries
API requests can fail — network hiccups, timeouts, or temporary disruptions happen. When they do, it's often safe to retry — as long as you're using idempotency keys.
These keys let Midaz know you're repeating a request, not starting a new one. That means we can avoid processing it twice, while still helping your system recover gracefully from errors.
Idempotency
Transactions
Midaz uses idempotency keys to guarantee that each transaction is processed only once — even if the same request is sent multiple times.
This protects against accidental duplicates and helps ensure data consistency in your system.
How to Generate an Idempotency Key
You create the idempotency key on your side. We recommend building an MD5 hash from the following fields:
- Transaction amount
- Source
- Destination
- Asset code
This keeps the key unique and predictable for retries.
How to Use It
When sending a POST request to /v1/transactions, include your idempotency key in the idempotencyKey query parameter.
Midaz stores this key in cache with the format hash:timestamp:status_request.
If the same key is received again within 60 seconds of a successful transaction, Midaz blocks the duplicate and returns an HTTP 409 response.
Cache & Tolerance Window
Idempotency keys are cached for 24 hours to optimize performance.
By default, the duplication window is 60 seconds, but you can customize this by including a tolerance query parameter in your request. This defines how long Midaz should consider two transactions as "the same."
For example:
A request sent after the initial 60 seconds — with a valid idempotency key and changed tolerance — will be treated as a new operation.
This gives you control over timing, while keeping your data safe from unintended repeats.
Preventing Entity Duplication
Beyond transactions, Midaz enforces unique names for all key entities — like Accounts and Ledgers.
If you try to create an entity with a name that already exists, Midaz blocks the operation and returns a clear message. This ensures your data stays clean, unambiguous, and easy to manage.