Skip to main content

Staying in Sync: external_execution_id & Idempotency

Two small mechanisms quietly keep the platform and your running workflow honest with each other. You rarely touch them directly — the Circus nodes handle both — but understanding them explains a lot of the platform's reliability, and one 409 error you might otherwise puzzle over.

external_execution_id — the link between two systems​

Circus tracks a run on its side; n8n runs it on its side. The external_execution_id — n8n's own execution ID — is the thread that ties the two together. Every callback your workflow makes (log, complete, terminate) carries it, and the platform uses it to line its record up with the real engine execution.

Why it matters:

  • It's how the platform can later query the engine's status and issue a remote stop — for example, when the reconciler needs to kill a run that's over its limit, or an operator terminates one from the UI. Without it, the platform can't reach into the engine, and such a run has to be left for manual intervention.
  • The platform captures it the first time your workflow calls back, and guards it under a lock: if it's not set yet, it's stored; if the same value comes again, that's a harmless no-op (safe for retries); but if a different value arrives while one is already stored, the callback is rejected with a 409 conflict. That last case prevents one execution from acting on another's record — so if you ever see a 409 EXTERNAL_EXECUTION_ID_CONFLICT, it means two different engine IDs reached the same platform execution, which shouldn't happen in a well-formed workflow.

The Init node stores this ID in the shared context, and every Circus node includes it automatically — you don't set it by hand.

Idempotency keys — no double-counting​

The other mechanism protects your cost data. Every log entry the nodes send carries an auto-generated idempotency key (a UUID). If a log call fails and n8n retries it, the same key is reused — so the platform recognises the repeat and skips the duplicate insert, returning the current tally instead of counting the step twice.

That's what makes retries safe: a network blip that sends a log twice won't inflate your reported cost or timeline. Like the execution ID, these keys are entirely internal — the nodes generate and manage them, and they're never exposed to you or configurable. The result is simply that your execution logs stay accurate even when the network doesn't cooperate.