Pure vs Effectful: Why My n8n Retry Policy Tags Nodes, Not Failures

Description and use

In n8n, nodes are tagged as pure or effectful with idempotency consideration. Only pure nodes and idempotent effectful nodes allow retries; others go to review, preventing duplicate side effects.

Problem

Determining retry behavior for n8n nodes based on whether they produce side effects and whether they are idempotent, rather than on error classification alone.

Outcome

After two weeks, 180 failures were logged: 164 pure node failures followed the old budget policy with ~70% first‑attempt success on repairable failures; 13 effectful node failures with idempotency keys had 12 successes on single retries; 3 effectful node failures without keys had zero retries and all went to review, preventing duplicate charges or emails.

Workflow

• Define NODE_POLICY mapping node names to kind (pure/effectful) and idempotent flag in a Code node.
• Use a Classify node to look up the failed node’s policy before inspecting the error.
• If the node is pure, apply the existing three‑bucket retry logic (retry_once, retry_backoff, review).
• If the node is effectful and idempotent, set action to retry_identical (byte‑identical retry with same idempotency key).
• If the node is effectful and not idempotent, set action to review (no retry).

Evidence

Every node in my production workflows now carries one of two tags: pure or effectful.

Source

Effectful nodes get a second field: idempotent — true if the call carries an idempotency key (or is naturally idempotent, like a PUT with a fixed resource id), false otherwise.

Source

Three lines, no ambiguity. The old error-classification code didn't disappear — it moved inside the pure branch, where the retry budget post still applies exactly as written.

Source

Three weeks on the new tags, ~180 failures logged across my workflows: 164 hit pure nodes → the old budget policy handled them; 13 hit effectful nodes with idempotency keys → all byte-identical single retries; 3 hit effectful nodes without keys → zero retries, all went to review.

Source