CONCEPT Retries and side effects collide
The whole reliability story so far — SDK auto-retry (6.3), fallback (6.4), even a client re-issuing a request after a timeout — assumes re-running a call is safe. For a read, it is. For a write with side effects (charge a card, send an email, create an order), a retry can double-execute: the first call succeeded but the response was lost, so the retry charges the customer twice.
| Property | Meaning | Safe to retry? |
|---|---|---|
| Idempotent | Re-running yields the same end state (GET, PUT to a fixed key, deterministic upsert) | 🟢 Yes — retry freely |
| Non-idempotent | Each run adds an effect (POST that creates, charge, increment, send) | 🔴 No — needs an idempotency key first |
DIAGRAM How a lost ack causes a double charge
→ server dedupes attempt 2
CODE The idempotency-key pattern
Generate the key once per logical operation and send it on every retry of that operation. The server records the key and returns the original result instead of re-executing.
import uuid # One key PER LOGICAL OPERATION — reused across ALL retries of it. def charge_card(customer, amount): key = str(uuid.uuid4()) # generated ONCE, outside any retry loop return _post_with_retry(key, customer, amount) def _post_with_retry(key, customer, amount, attempts=3): for _ in range(attempts): try: return payments.post( "/charges", headers={"Idempotency-Key": key}, # SAME key each attempt json={"customer": customer, "amount": amount}, ) except TransientError: continue # server dedupes on the key → no double charge raise RuntimeError("charge failed after retries")
Design tools to be inherently safe
Where you own the tool, prefer designs that are naturally re-runnable:
- Upsert by natural key — "create order for cart
C123" returns the existing order if it already exists, instead of a new one. - Check-then-act with a unique constraint — let the DB reject the duplicate.
- Reversible / two-phase — reserve, then commit; a lost ack leaves only a harmless reservation.
EXAM TRAPS
PRACTICE
Q1 · An agent's "send_invoice_email" tool times out. Retry as-is?
Not safely — sending email is non-idempotent (each retry sends another). Add an idempotency key (or a per-invoice "already sent" guard) so a retry after a lost ack doesn't send twice.
Q2 · Why is generating the idempotency key inside the retry loop a bug?
Each attempt would carry a different key, so the server can't recognise attempt 2 as a retry of attempt 1 — it executes both. The key must be generated once per logical operation and reused on every retry.
Q3 · Which of these are safe to retry without special handling: GET user, PUT profile to a fixed key, POST create-order?
GET (read, no effect) and PUT to a fixed key (idempotent — same end state) are safe. POST create-order is not — it creates a new record each time; make it idempotent (upsert by cart key or an idempotency key) before retrying.