agent lost the idempotency key on a journal POST retry and the duplicate entry failed the ledger balance check

TL;DR

The idempotency key is the journal's identity across retries; losing it turns the retry into a new, independent POST. First stop the bleeding: find the duplicate journals from the retry and reverse the extra ones so the ledger balances again. Then fix the retry path so the key is generated once, stored with the job state, and attached to every attempt including retries. A journal that fails the balance check because of a duplicate is really reporting a posting-protocol failure, and the key is the protocol.

agent lost the idempotency key on a journal POST retry and the duplicate entry failed the ledger balance check

Use this when

• Two or more journals exist for one intended adjustment after an agent retry.
• The ledger balance check fails or a duplicate is flagged on the retried entry.
• The agent's logs show the retry used a new or missing key.

Not for this skill when

• Only one journal exists and the balance check fails for another reason, such as an unbalanced entry. Fix the entry itself.
• The duplicate was posted by a human alongside the agent. Coordination is the fix; the key protocol still helps the agent side.

Steps

1. List the duplicate journals with creation times, keys or references, and amounts, and confirm they represent one intended posting. Verify: the intended count versus actual count is established
2. Reverse the extra journals, keeping the earliest or the referenced original, with memos citing the duplication. Verify: exactly one journal's effect remains and the balance check passes
3. Generate the idempotency key once per intended journal at job start and persist it with the job state before the first POST. Verify: the key exists in durable state before any network call
4. Change the retry logic to load and attach the stored key on every attempt, and to look up the key before re-POSTing after an ambiguous result. Verify: a simulated retry reuses the stored key
5. Test the full path with an induced failure in a safe scope and confirm one journal and one key in the audit trail. Verify: the test shows exactly one posting under retry conditions

Variant phrasings

lost idempotency key journal POST retry duplicate entry

The lost-key phrasing.

journal retry idempotency key persistence agent

When making retries key-preserving.

Compatibility: Journal posting APIs with idempotency keys in NetSuite, Sage Intacct, and custom GL services.

Why it happens

Idempotency keys only work when they are stable: the same key on every attempt of one logical operation, and different keys for different operations. Generating the key at retry time, or holding it only in memory that the retry path does not share, breaks the stability the server depends on. The ledger balance check then does its job as the last line of defence, catching the duplicate the protocol was supposed to prevent, and the reversal plus the protocol fix together restore both the books and the safety.

Edge cases / pitfalls

• Keys must be unique per intended journal; reusing one key for two different adjustments merges them in the server's eyes.
• If the API reports the original journal when a duplicate key arrives, the agent should treat that response as success and adopt the returned journal id.
• Log key generation and reuse; a key appearing twice for different journals is a generation bug to catch early.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstBGMD6zxjK4-RhUDOlGv-g