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 and 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, such as 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.