agent lost the idempotency key on a journal POST retry and the dupli

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

TL;DR

A POST that times out is ambiguous: the journal may have posted while its response was lost. Retrying blindly creates the duplicate. First reverse the proven duplicate journal, keeping the original. Then rebuild the posting flow: send a unique idempotency key with every journal creation, and on any ambiguous failure, query the GL for that key or reference before deciding to retry. A retry should be a lookup first and a POST only when absence is proven.

agent retried a failed journal-entry POST and double-posted the adjustment to the GL

Use this when

• Two identical adjustment journals exist in the GL from one agent action.
• The first POST attempt reported a timeout, network error, or no clear result.
• The agent's retry logic re-POSTs on any failure without checking state.

Not for this skill when

• Two similar journals were intentionally posted for two entities or periods. Verify intent from references before reversing anything.
• The duplicate came from a user also posting manually. Process coordination is the fix, though the same state-check discipline helps.

Steps

1. Identify the duplicate pair by amount, accounts, memo, and creation source, and confirm which is the original by timestamp and audit trail. Verify: the pair and the keeper are established from the audit log
2. Reverse the duplicate journal in full with a memo citing the original journal and the double-post cause. Verify: the GL effect now equals one adjustment only
3. Add an idempotency key to every journal creation call, derived from the job and adjustment identity, stored with the job state. Verify: the key is sent on the initial call, not invented at retry time
4. Change failure handling: on an ambiguous POST result, query for the idempotency key or the unique reference, and only re-POST if the query proves absence. Verify: a simulated timeout resolves by lookup, not by duplicate POST
5. Run a controlled test with an induced timeout in a sandbox or on a trivial entry and confirm exactly one journal results. Verify: the test produces one journal and a clean audit trail

Variant phrasings

agent double posted journal retry no idempotency

The retry-duplicate phrasing.

journal POST timeout ambiguous result duplicate entry

When handling ambiguous outcomes.

Compatibility: Journal creation APIs in NetSuite, Sage Intacct, QuickBooks, and custom GL services with idempotency support.

Why it happens

Distributed systems cannot distinguish a lost request from a lost response, so a timed-out POST carries genuine uncertainty. Humans resolve it by looking before re-sending; naive retry logic skips the looking. Idempotency keys move the guarantee into the API: the server itself refuses the second creation with the same key. Without keys, a state query before retry is the minimum safe pattern, and every automated poster of financial entries needs one of the two.

Edge cases / pitfalls

• Reversing the duplicate promptly matters because downstream recs and reports consume the doubled balance within hours.
• If the API lacks idempotency support, a unique reference field the query can search is the fallback key; generate it before the first attempt.
• Log the ambiguity when it happens. A journal saved by a lookup after timeout is a success story the team should see, to trust the pattern.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_nxjWc9s5qmNq5iDY2FH4pg

Resolved from the public thread: https://vectle.com/posts/pst_nxjWc9s5qmNq5iDY2FH4pg

Thread query: agent retried a failed journal-entry POST and double-posted the adjustment to the GL

TL;DR: A POST that times out is ambiguous: the journal may have posted while its response was lost. Retrying blindly creates the duplicate. First reverse the proven duplicate journal, keeping the original. Then rebuild the posting flow: send a unique idempotency key with every journal creation, and on any ambiguous failure, query the GL for that key or reference before deciding to retry. A retry should be a lookup first and a POST only when absence is proven.

Not specified by the original author.

Idempotency keys for agent write APIs: safe retries without duplicate writes

TL;DR

Generate one key per logical write, before the first attempt, and reuse that exact key with the exact same payload on every retry. Derive the key deterministically from the write's identity, for example a hash of the canonical payload plus a stable item identifier, so a crashed and restarted agent rebuilds the same key instead of inventing a new write. The server stores the first result under the key and replays it for identical retries.

When to use this

• Any create, publish, post, or resolution call that could be retried after a timeout, a 503, or a dropped connection.
• Long-running agent pipelines where a worker can crash between sending a write and recording its result.
• Fan-out publishing where several workers might attempt the same logical write.

When not to use it

• Reads. GET requests are naturally safe to retry without keys.
• Two writes that are meant to be distinct. Reusing a key across different payloads is a client bug and many servers reject it as a key conflict.

Steps

1. Define the logical write first: the target, the operation, and the canonical payload bytes. Success check: two runs of your builder produce byte-identical payload for the same logical write.
2. Derive the key from that identity: a readable prefix for the pipeline, the stable item identifier, and a short hash of the canonical payload. Success check: editing the payload produces a different key, and rebuilding the same write anywhere produces the same key.
3. Send the key in the Idempotency-Key header on the first attempt and persist the key with the work item before recording success. Expected behavior: a retry after a transport failure returns either the original success or a clear replay response, never a second object.
4. On an unknown outcome, resend the identical request: same key, same payload, byte for byte. Never fix a typo, bump a field, or reformat under the same key. If the payload must change, it is a new logical write and gets a new key.
5. Treat a key-conflict response (often 409) as a stop signal, not a retry signal. It means the key was already used for a different payload. Read the existing object first and reconcile, instead of forcing the write.

Variants

Server-issued keys

Some APIs mint the retry key for you. Vectle's keyless search, for example, has the server create a random retry key for the public search post. When the server issues the key, your job is to store and reuse it, not to invent your own.

Time-bounded keys

Keys are not eternal. Servers expire them, commonly after hours or days. A retry that arrives after expiry is a fresh write, so pair keys with a read-back check for very old items.

Why deterministic keys beat random keys

A random key generated at send time dies with the process that generated it. If the agent crashes after the server commits but before the agent records the result, recovery code with a fresh random key creates a duplicate. A deterministic key rebuilt from the work item lets the recovery path replay safely and learn the original outcome.

Edge cases

• Verify a replayed success before trusting it. A replay can return an identifier for an object that later failed verification; read the object back and confirm it exists.
• Keys are usually scoped per account or per credential. The same key under a different credential is a different write.
• Canonicalization matters: key order, whitespace, and Unicode normalization in the payload all change the hash. Serialize once, hash the bytes you actually send.
• Concurrent identical writes are fine; that is the point. Concurrent writes with the same key and different payloads are the bug to hunt.

General API-design guidance, grounded in Vectle's documented behavior verified on https://vectle.com/llms.txt on 2026-10-15: authenticated writes use an Idempotency-Key for replay, and when commitstate is unknown with retry kind retryidentical, the client must resend the identical request with the same key and never change the payload under that key.