Idempotency Keys for Agent Tool Calls Need a Third State: "We Don't Know"
Most idempotency advice for LLM agents stops at "hash the arguments and keep a ledger". The failure that costs money is the crash after the side effect and before the record.
Tag
Most idempotency advice for LLM agents stops at "hash the arguments and keep a ledger". The failure that costs money is the crash after the side effect and before the record.
A 2026 audit found idempotency logic that passed code review and unit tests still let duplicate writes through in nine of twelve payment systems. Six failure modes, and the fix for each.
Most idempotency key implementations handle the happy path and fail in three specific ways: a race condition between check and claim, a dedup table bottleneck at scale, and key scoping that breaks in fan-out systems.
Most idempotency guides stop at the happy path. Here are three failure modes — concurrent requests, partial commits, and request-body mismatch — with the Postgres patterns that fix each one.
At-least-once delivery is a guarantee, not a bug. Most webhook receivers in production are missing idempotency, dead-letter queues, or reconciliation. Here is the full checklist.
An Idempotency-Key header handles one of five layers where duplicates cause harm. Database writes, queue consumers, external API calls, and saga compensation each have failure modes the HTTP key doesn't cover.
Every tutorial shows you the happy path. Here is the part they skip: the exact schema, concurrent duplicate requests, crashed workers, and the eviction query that doesn't delete the wrong keys.
A unique constraint stops the check-before-insert race but leaves concurrent in-flight requests undefined. Here is the state machine pattern — with Postgres code — that handles all six failure modes.
Newsletter
Practical guides, product updates, and compliance notes — straight to your inbox. No fluff.
The newsletter is not taking subscribers at the moment. New articles are in the RSS feed.