Standardize idempotency-key handling across Increase, Column, and Modern Treasury
domain: banking-general · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
For Increase, generate a pre-allocated unique string (up to 200 characters) per creation call and send it as the Idempotency-Key header; check the Idempotent-Replayed response header to detect when a call returned a previously created object instead of a new one.
For Column, send a unique client-generated Idempotency-Key header per request; a repeated key on the same endpoint returns the original created object (e.g., transfer) instead of creating a duplicate.
For Modern Treasury, pass a unique idempotency key in the request headers; the key and result are retained for a bounded window (24 hours), and repeated calls within that window replay the original response.
Choose a consistent key-generation strategy across all three — e.g., deterministic keys derived from your own internal object ID such as an invoice or payment order ID — so retries after process crashes or timeouts remain safe.
Build retry logic that always reuses the same idempotency key for a given logical operation, treating a network-level failure with no response as 'retry with the same key,' not 'assume failure and mint a new key.'
Known gotchas
Modern Treasury's idempotency window is time-bounded (24 hours) — a retry issued after the window expires is not deduplicated and can double-originate a payment.
Idempotency keys are typically scoped per endpoint/object type, not globally — reusing the same key across two different endpoints (e.g., an ACH transfer and a wire transfer) on the same provider does not guarantee dedup across them.
None of the three providers make idempotency automatic — omitting the header entirely, not a client-library bug, is the most common cause of accidental duplicate payment origination in production.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?