Idempotency

Idempotency is a property of an operation where performing it multiple times has the exact same effect as performing it once — calling the operation again doesn't change the outcome or cause unintended side effects beyond the first call. It's a critical concept for any system that involves network calls, because networks are inherently unreliable: a request can time out or a response can get lost even though the operation actually succeeded on the server, and the only safe way to handle that uncertainty is to retry — but retrying is only safe if the operation is idempotent, otherwise a retried "charge $50" request could charge the customer twice. Why it matters for AI/SaaS builders: idempotency is foundational to reliable payment processing, webhook handling, and any AI agent system that can take real-world actions with retries built in — an agent (or a distributed system generally) that retries a failed tool call needs a guarantee that the retry won't duplicate a real-world effect like sending a duplicate email, double-charging a card, or creating two support tickets for the same issue. Stripe's API is a widely-cited real-world example: it requires an `Idempotency-Key` header on charge-creation requests specifically so a client can safely retry a request that timed out without risking a duplicate charge. How it works: idempotency is typically implemented by having the client generate a unique key for a given logical operation (often a UUID) and send it with the request; the server checks whether it has already processed a request with that exact key — if so, it returns the same result as the original successful call without re-executing the underlying side effect (charging the card, sending the email); if not, it processes the request normally and records the key alongside the result for a period of time, so any retry with the same key is safely recognized. Naturally idempotent operations (like `PUT /users/42 {name: "Alex"}` — setting a field to a specific value repeatedly always results in the same final state) don't need this mechanism explicitly; naturally non-idempotent operations (like `POST /orders` creating a new order, or an increment operation) do. Worked example: a checkout flow calls `POST /charges` with `Idempotency-Key: a1b2c3-order-9284` to charge a customer $49. The request reaches the payment processor, the charge succeeds, but the network connection drops before the success response reaches the client. The client's code, seeing what looks like a failed request, automatically retries the exact same `POST /charges` call with the identical idempotency key. The payment processor recognizes the key has already been used for a successful charge, does not charge the card a second time, and simply returns the original success response — the customer is charged exactly once despite the retry, purely because the operation was designed to be idempotent.