Idempotency explained

Idempotency means that performing the same operation multiple times produces the same result as performing it once. In practical terms: if you accidentally send a payment request twice, an idempotent API charges the customer once. A non-idempotent API charges them twice.

The concept comes from mathematics — a function f is idempotent if f(f(x)) = f(x). In software, it's a design guarantee that protects against the inevitable: network timeouts, retry loops, duplicate webhooks, and crashed processes that restart mid-execution. Every automation that touches money, data, or user-facing actions needs idempotency baked in. Unlike generic AI automation posts, this guide shows real CodeWords workflows — not just theory.

Stripe's API documentation explains their idempotency key system — a pattern now adopted across the industry. According to a 2025 Postman API survey, 65% of developers consider retry safety a top concern when building integrations.

Related: AI workflow automation, webhook payload explained, what is a workflow engine, API authentication methods explained, workflow automation tools, CodeWords integrations, CodeWords templates.

How idempotency works in practice

There are two main implementation patterns.

Idempotency keys. The client generates a unique key (usually a UUID) and sends it with each request. The server stores the key alongside the result. If the same key arrives again, the server returns the stored result instead of re-executing the operation. Stripe, PayPal, and most payment APIs use this pattern. The key is typically sent as an HTTP header: Idempotency-Key: abc-123-def.

Natural idempotency. Some operations are inherently idempotent. HTTP GET is always idempotent — reading data doesn't change it. HTTP PUT (replace a resource entirely) is idempotent — putting the same data twice results in the same state. HTTP DELETE is idempotent — deleting an already-deleted resource is a no-op. HTTP POST is not naturally idempotent, which is why POST endpoints need explicit idempotency handling.

The distinction matters for automation platforms. When a workflow step makes a POST request to create a record, and the workflow retries after a timeout, the platform needs to prevent duplicate creation. CodeWords workflows run in ephemeral E2B sandboxes with state persistence via Redis, which means idempotency keys can be stored and checked across retry attempts automatically.

Why automation workflows need idempotency

Automation multiplies the idempotency problem. A manual process — a human clicking a button — rarely sends duplicate requests. An automated workflow running on a schedule, triggered by webhooks, or retrying after failures can easily fire the same action multiple times.

Common scenarios where idempotency saves you:

• Webhook deduplication. Many services send the same webhook multiple times as a delivery guarantee. Stripe can send the same payment_intent.succeeded event two or three times. Without idempotency checks, your workflow processes the payment multiple times.
• Retry after timeout. A workflow step calls an API, the network times out, and the workflow retries. The first call may have actually succeeded — the timeout was just on the response, not the request. Without idempotency, you've now created two records.
• Concurrent execution. Scheduled workflows that take longer than their interval can overlap. If a daily sync takes 25 hours, two instances run simultaneously. Without idempotency, both instances create duplicate entries.

Platforms like Zapier handle deduplication at the trigger level — they track which trigger events have been processed. But step-level idempotency (ensuring each action within a workflow is safe to retry) is usually left to the developer. n8n provides some built-in deduplication for triggers but requires manual handling for action steps.

Implementing idempotency in CodeWords workflows

CodeWords provides several mechanisms for idempotent workflow design.

Redis-backed state tracking. Before executing an action, the workflow checks Redis for a completion record keyed by a unique identifier (webhook ID, record ID, or computed hash). If found, the step skips. This pattern works for scheduled workflows and batch processing.

Upsert operations. Instead of "create" operations (which duplicate), CodeWords workflows use "upsert" (update-or-insert) when writing to databases like PostgreSQL or CRMs like Salesforce. The unique key ensures the record is created once and updated on subsequent runs.

LLM response caching. LLM calls are expensive and non-deterministic. Caching the response for a given input hash means retries return the same result without additional API costs. This is especially valuable in deep research workflows where a single run may make dozens of LLM calls.

Idempotency and AI automation

AI steps add a wrinkle: even with the same input, an LLM may produce different output. This means "same result" needs a looser definition for AI-powered workflows. The idempotency guarantee applies to the action (the write, the API call, the notification), not to the AI's reasoning. Cache the action result, not just the prompt.

For example, a lead scoring workflow should be idempotent at the CRM-write level: the same lead shouldn't be scored and written twice. But the score itself might vary between runs if the LLM is called again. The solution is to separate the AI reasoning step (non-idempotent, cached for cost) from the write step (idempotent, deduplicated by lead ID).

Quick reference for HTTP method idempotency

Method Idempotent? Safe?

| GET | | Yes | | Yes |

| PUT | | Yes | | No |

| DELETE | | Yes | | No |

| POST | | No | | No |

| PATCH | | No | | No |

Build retry-safe workflows at codewords.agemo.ai — CodeWords handles state persistence so your automations don't double-fire.