> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency guide rewritten

> The Retries and Idempotency guide is now rewritten with clarified scope, auto-generated keys, error behavior, cross-product comparison tables, and updated examples.

<Badge stroke icon="calendar-days" iconType="regular">March 16, 2026</Badge> <Badge stroke icon="file-code" iconType="regular">Documentation update</Badge> <Badge color="purple" size="lg" stroke icon="eye" iconType="regular">Review recommended</Badge>

## Affects

***

Teams implementing retries and idempotency for transaction endpoints.

This update applies to the public documentation portal. It does not change the runtime API behavior unless the linked product documentation says otherwise.

## What changed

***

The [**Retries & Idempotency**](/en/reference/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?"

## Impact

***

This is a documentation update. Existing integrations do not need a migration from this release note alone.

## What you need to do

***

<Steps>
  <Step>
    Review the clarified idempotency scope and retry behavior before changing transaction retry logic.
  </Step>
</Steps>

### Deadline

None.

### Why

The rewrite clarifies which endpoints support idempotency and how keys behave after validation or balance errors.