Skip to content
atom®technologies
Engineering notes

API idempotency: what survives a retry?

How command identity and recorded outcomes make API retries safe. Inspect a Rust reference study and the persistence boundaries it does not establish.

The operation may already have happened

A caller sends a transfer instruction. The receiver commits the transfer, but the acknowledgement never reaches the caller. From the caller's perspective, the request failed. The money movement may already be complete.

Repeating the instruction creates a second problem unless the receiver can recognize the original intent. A timeout describes what the caller observed. It does not establish the receiver's final state.

Identity needs a meaning

Give the command a stable identity and bind that identity to its contents. A replay with the same identity and operation can return the recorded result. A request that keeps the identity but changes the amount is a conflict that the system must surface.

The record of the operation and its effect must agree. In a persistent system, storing the deduplication record separately from the state change introduces another failure window. The transaction or coordination boundary has to cover the invariant being promised.

Ask what the demonstration proves

Our reference study executes three bounded scenarios in Rust: an exact replay, a changed request under the same identity, and a lost acknowledgement followed by a retry. Each run starts with its own in-memory state and exposes the commands, outcomes, and resulting balances.

That scope makes the state transitions inspectable. Persistence through a process restart, concurrent callers, and effects in another service require additional mechanisms and tests. An assessment identifies which of those boundaries matter for the system being commissioned.

Use the result to make a decision

An assessment should connect a reproduced failure to the decision it changes. Establish what must remain true, locate the component that owns the relevant identity and state, and compare repairs at that boundary with a broader replacement.

The useful deliverable is a plan with acceptance evidence: what will be tested, which failures will be exercised, and what result would stop a rollout. A recommendation to keep an existing design should be supported with the same care as a recommendation to replace it.