Idempotency
Opt-in safe retries with the Idempotency-Key header — 24-hour replay cache, conflict detection, and the privacy trade-off made explicit.
Safe retries
Network timeouts leave you not knowing whether a conversion happened — and whether retrying will bill you twice. Send an Idempotency-Key header on any POST and retries become safe:
curl -sS -X POST "https://api.transmute.403fin.io/v1/convert?to=camt.053" \
-H "Authorization: Bearer $TRANSMUTE_KEY" \
-H "Idempotency-Key: stmt-2026-07-05-batch17" \
-H "Content-Type: text/plain" \
--data-binary @statement.mt940
The first request executes normally and its response is cached for 24 hours. A retry with the same key and the same body gets the cached response verbatim, marked:
Idempotency-Replayed: true
Replays are never billed and never consume quota.
The rules
| Rule | Behavior |
|---|---|
| Key format | 1–255 characters; anything else is a 400 |
| Cache scope | Per API key + idempotency key + SHA-256 of the body |
| Same key, different body | idempotency-conflict 409 — pick a new key |
| Cache lifetime | 24 hours |
| Large responses | Responses over 1 MiB are not cached (the request still succeeds) |
Choose keys that identify the logical operation — a statement id, a file hash, a job id — not random values (a random key per attempt defeats the purpose).
The privacy trade-off, stated plainly
transmute's headline posture is that message contents are never stored. Idempotency is the single documented exception: the cached response to a convert call contains the converted message, held in the replay cache for 24 hours. The raw request body is never stored (only its hash, for conflict detection).
If that retention is unacceptable for your data, simply omit the header — idempotency is entirely opt-in, and nothing else about the API changes.