Idempotency Key

Idempotency means that making multiple calls to the same operation produces exactly the same result as making it once; a unique idempotency key should be generated for each business action and the result persistently bound to that key to prevent duplicate execution.

An idempotency key is a globally unique key generated by the client for each operation (usually a UUID) and sent to the external service with the request; the server checks whether the key already exists before processing, and if it does, returns the previous result without executing the actual action again.

A common technique for achieving idempotency is for the client to generate a unique idempotency key sent with the request, while the server records the result associated with that key and returns the cached result upon receiving a duplicate request.

Common methods for achieving idempotency include assigning a unique request ID (idempotency key) to each write operation, or using conditional writes (compare-and-swap) that only execute when the target data is in the expected state.

Idempotency means that the same operation should yield the same final result regardless of whether it is executed once or multiple times; a common implementation is to generate a globally unique request ID (such as a UUID) for each request for server-side deduplication.

When validation fails, the specific error should be fed back to the model for correction, but retries must have limits on the number of attempts, timeout duration, and cost control, as retries increase latency and resource consumption.

For LLM calls, 5xx errors and timeouts are worth retrying, while retrying 400-class errors is usually meaningless; retrying requests with side effects may cause duplicate billing, so idempotency keys or request deduplication should be incorporated into the design.

Retries only apply to idempotent requests or operations that can be safely repeated, and calls with side effects should use idempotency keys.

A timeout should be treated as "I don't know" rather than "no"; the solution is to have code generate an idempotency key and send it with the retry, so that the booking system recognizes the same key and returns the first result.

Key design points for idempotency keys include generation timing (it should be generated before the first request, not regenerated on each retry), scope (usually bound to a specific user and operation type), validity period (commonly 24 hours) and storage (which needs persistence and must consider concurrent atomicity).

In the community discussion, the most agreed-upon approach was to push deduplication responsibility down to the API layer, with the Agent carrying an idempotency key in each request and the server recognizing duplicate keys and returning the first result.

The classic approach of payment platforms such as Stripe is to use idempotency keys, with the server recognizing duplicate keys and returning the first result rather than executing the operation twice.

Stripe's idempotency implementation allows returning an error when request parameters are inconsistent, preventing the key from being misused.

For money transfers, emails and external writes, idempotency keys are always needed; idempotency keys prevent duplication but cannot solve the problem of sending an unapproved payload.

Binding a unique idempotency key to each state-changing action of an agent and checking that key on retry, returning the cached result directly if the action has already completed, can provide idempotent protection.

Approvals must be bound to the exact action (such as this order, this amount, this idempotency key), and once the state changes, approval must be obtained again.

The effectiveness of an idempotency key depends on contract details: its scope, whether the consistency of request parameters for the same key is validated, the retention period, and how concurrent requests with the same key are handled; merely carrying an idempotency key does not constitute a permanent duplicate-prevention guarantee.

For external tools without an idempotency key, the second run after a failure is a real replay, and the target system receives two calls.

At-most-once execution requires an end-to-end deduplication mechanism (such as idempotency keys, call logs, or idempotency support in the target system), covering retry, restart and network partition scenarios beyond the decision layer.

In scheduling scenarios, blind retries without an idempotency key may generate two identical appointments, occupying another customer's time window; the correct approach is to resubmit with the request ID, and the server uses the idempotency key to determine whether it is a first execution or a duplicate request.