Skip to main content
March 16th, 2026 Improved The Retries & Idempotency guide received a major rewrite with clearer scope, better examples, and new reference tables.

Key changes


  • Scope clarified — Idempotency support applies to six transaction endpoints specifically, not all Midaz APIs
  • Auto-generated keys — If you omit the X-Idempotency header, Midaz generates a key automatically using a SHA-256 hash of the request body
  • Error behavior — Midaz deletes idempotency keys on validation and balance errors, so you can safely retry with the same key after fixing the issue
  • Cross-product comparison — A new table shows idempotency support across Midaz, Matcher, TED, Pix Indirect, Pix Direct, and Reporter, including header names, TTL, and scope
  • Entity uniqueness constraints — A new table lists the uniqueness rules per resource (Ledger, Asset, Segment, Account, Account Type) with their corresponding error codes
  • Updated code examples — Generic pseudo-code replaced with concrete HTTP requests using real endpoints and payloads
  • New FAQs — “Can I reuse a key across different endpoints?” and “Can I reuse a key across different organizations or ledgers?”