Why is idempotency a prerequisite for safe agent retries, and what breaks when a non-idempotent tool is retried?

Short answer·Medium·4.0 · 0·~3 min·Relevant atAnthropic OpenAI

Attempt it

Explain why idempotency matters for safe retries in an agent. Give one concrete example of a non-idempotent tool and the failure that occurs when the agent retries it after a transient error.

Free · 2 AI evals / day

Quick reference

TL;DR

A timeout is ambiguous, so a blind retry can repeat a side effect. Idempotency makes the repeat harmless; idempotency keys are the standard fix for payments and sends.

Memory aid

Easy to grasp

Imagine you text a friend to pay back ten dollars, but your phone says 'failed to send' even though it actually went through. If you resend it, your friend gets paid twice. The trouble is you cannot tell whether the first one really worked. An agent calling a tool over the network has the same problem. When it gets a timeout, it does not know if the action happened or not. If it just tries again, it might charge a card twice or send the same email twice. The clean fix is to attach a unique sticker to each request. The server remembers the sticker, so when it sees the same one again it says 'I already did this' instead of doing it a second time. That makes trying again safe even when you cannot tell what happened.

Key concepts

Idempotency Idempotency Keys Retries and Timeouts

Detailed answer & concept explanation

~8 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.

Quick scan · 2–4 min

Everything important, quickly.

Define idempotency, explain why a timeout is ambiguous about commit, walk the double-charge failure end to end, then present idempotency keys scoped per action, the transient versus definite error split with backoff, and the at most once fallback for tools that cannot be keyed.

Code example

python

import uuid, time, random

def call_tool_with_retry(tool, args, max_attempts=4):
    # One key per LOGICAL action, reused across all retries.
    key = str(uuid.uuid4())
    for attempt in range(max_attempts):
        try:
            return tool(args, idempotency_key=key)
        except TransientError:        # timeout, 503, connection reset
            if attempt == max_attempts - 1:
                raise
            time.sleep(2 ** attempt + random.random())  # backoff + jitter
        except ClientError:           # definite 4xx: never retry
            raise

Side-by-side

Aspect	Idempotent tool	Non-idempotent tool
Examples	Read, GET, upsert by id	Charge card, send email, append row
Effect of a blind retry	Harmless, state unchanged	Duplicate side effect
Retry policy	Retry freely with backoff	Retry only with an idempotency key
Fallback when key is impossible	Not needed	Human approval or compensating action

Real-world examples

Real products, models, and research that use this idea.

Stripe's payment API requires an Idempotency-Key header on charge requests; a retry with the same key returns the original charge instead of billing the card again.
Temporal and AWS Step Functions model agent and workflow activities as retryable, pushing teams to make each activity idempotent so the orchestrator can safely replay it.
LangGraph and the Anthropic SDK leave tool side-effect safety to the developer, so a charge or send tool needs its own idempotency key before the agent loop retries it.
Frontier coding agents in Cursor and Claude Code retry transient API failures with exponential backoff, while a confirmed bad request is surfaced rather than blindly retried.

Interviewer follow-ups

What an interviewer would ask next. Try answering before peeking at the approach.

QHow do you generate and scope an idempotency key so all retries of one action share it but distinct actions do not collide?

QA downstream API has no idempotency support. How do you still make a send or charge safe to retry?

QHow should the retry policy differ between a 503, a timeout, and a 400 from a tool call?

Don't say this

Red flags and common mistakes that signal junior thinking. Click to expand.

Most common mistake

Retrying every failed tool call the same way. A timeout on a payment or send is ambiguous, so a blind retry can duplicate the side effect even though the first attempt already succeeded.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

References

Primary sources. Skim if you want the original framing.