Production-grade error handling in n8n — the complete guide

Most workflow failures are boring. A vendor times out. A token expires. A webhook sends the same payload twice. A field arrives null because a sales rep skipped it. The difference between a demo workflow and a production workflow is not more nodes. It is a failure model.

Start with failure classes

Error Trigger is not enough

n8n Error Trigger workflows are useful for catching unexpected failures, but they should not be the whole strategy. Expected failures belong in the main workflow with explicit branches. If an invoice has no ABN, that is not an exception. It is a business state that needs review.

Retry policy

Retry only operations that are safe to repeat. Reads are usually safe. Writes are safe only when the target supports idempotency or you provide a stable external ID. Use short backoff for rate limits and longer backoff for outage signals. Stop after a fixed number of attempts and store the payload.

Circuit breakers in n8n

A circuit breaker prevents one unhealthy service from consuming every execution slot. Store service state in Postgres, Redis, Airtable, or another durable store. After three to five failures in a short window, mark the service open and skip calls for a cool-down period. After the window, allow one test call. If it works, close the circuit.

Dead-letter queues

A dead-letter queue is not always a message broker. For SMB builds, a table is enough: source, payload, error class, error message, workflow version, retry count, owner, and status. The key is replay. A second workflow should let the owner retry one record, retry a filtered batch, or mark records as ignored with a reason.

Alerting without noise

The worst alert is one that fires for every retry. Alert only when a human decision or vendor action is needed. Send Slack for urgent business impact, email for daily summaries, and dashboards for trends. Include the workflow, failing node, customer or record ID, error class, and a replay link.

Execution logging

Keep business counters outside raw n8n execution logs. Raw executions are useful for debugging but poor for management reporting. Log records processed, records skipped, external cost, latency, retry count, and recovered failures. That is what lets a client trust the workflow after month three.

A complete error workflow, node by node

Here is the exact shape of an error-resilient external-write workflow that NexFlow ships on every client engagement. 11 nodes total. Each one earns its place.

1. Trigger — webhook or schedule. Captures the input event ID (or generates one) and stamps a workflow execution UUID.
2. Idempotency check — Postgres Select against an idempotency_keys table keyed by (event_id, operation). If a row exists, route to "already processed" branch and return the stored result. If not, continue.
3. Circuit-breaker read — Postgres Select against a service_state table for the target vendor. If state is OPEN, route to the dead-letter queue with a "circuit open" reason. If HALF_OPEN, mark this call as the probe.
4. Validation — Function node that checks the schema and business rules. Missing required fields route to a "permanent failure" branch with a typed error class; bad enums route to "data drift" alert; everything else continues.
5. External call — HTTP Request or vendor node with continueOnFail off (so n8n's native retry can fire). Set vendor-specific timeout (we use 30s for HubSpot, 60s for OpenAI streaming, 8s for status-check endpoints).
6. Error router — IF node that branches by HTTP status: 429 → retry-backoff branch; 5xx → retry-then-circuit branch; 4xx (not 429) → permanent failure branch; 2xx → success branch.
7. Retry-backoff branch — n8n Wait node with exponential delay (1s, 4s, 16s up to 5 tries), then loops back to step 5. After max retries, falls through to dead-letter.
8. Circuit-breaker write — Postgres Insert into service_state incrementing the failure counter. If the counter crosses the threshold (we use 5 failures in 60 seconds), flip the state to OPEN with a cool-down timestamp.
9. Idempotency write — on success, Postgres Insert into idempotency_keys with the response payload. Future replays of the same event hit step 2 and short-circuit.
10. Dead-letter write — Postgres Insert into dead_letter with {event_id, payload, error_class, error_message, workflow_version, retry_count, owner, status: 'pending_review'}.
11. Alert — Slack node, but only for permanent failures and circuit-opens. Retries do NOT alert. The Slack message links to the replay workflow.

A replay workflow lives next to the main one. It reads one or many rows from dead_letter, gives the operator a chance to edit the payload (n8n Form Trigger is the easy way), then re-injects through the main workflow's trigger with a replay: true flag that bypasses some validation but still respects idempotency.

Four real production incidents and what the workflow caught

1 · OpenAI rate-limit cascade (Feb 2026)

OpenAI dropped a Tier 4 customer to Tier 3 mid-day without notice. Our client's invoice-classification workflow started hitting 429 on roughly 12% of requests. The retry-backoff branch absorbed it; no executions failed. The Slack alert never fired because nothing reached "permanent." Total user-visible impact: 0. Total operator action required: 0. We only noticed because the per-execution latency P95 doubled for 90 minutes; the latency alarm caught it.

2 · Xero schema change (Mar 2026)

Xero changed the response shape of one tax-treatment field from a string to a nested object. Our validation node caught the schema mismatch on the first call, dead-lettered the bill, and alerted. The fix was a one-line node update. The pattern that made this catchable: we hash-validate every external response shape against a stored JSON schema, not just the fields we use, so cosmetic upstream changes still surface.

3 · Webhook replay storm (Mar 2026)

A buggy upstream sent the same Stripe webhook 47 times in 4 minutes. Without idempotency, that would have been 47 duplicate Xero bills, 47 Slack messages, and a real refund disaster. With idempotency on the stripe_event_id, the workflow processed exactly one. The dead-letter queue showed 46 "already processed" entries — visible, traceable, no harm done.

4 · HubSpot 6-hour outage (Apr 2026)

HubSpot's contacts API went down for the better part of a US business day. Circuit breaker tripped after 5 consecutive 503s, stayed open for the cool-down (we set 5 minutes initially, extended to 30 minutes once we saw the outage wasn't transient). 2,100 lead events queued in the dead-letter table during the outage. When HubSpot returned, the replay workflow drained the queue in 22 minutes. The client noticed nothing.

Frequently asked questions

How do I handle errors in n8n?

Use Error Trigger for unexpected crashes, explicit branches for expected business failures, retries for transient API errors, and dead-letter storage for anything that needs review.

What is a circuit breaker in n8n?

It is a stateful guard that pauses calls to a failing service, protects execution capacity, and tests recovery after a cool-down period.

How to set up dead-letter queues in n8n?

Write the failed payload and error metadata to a durable store, notify the owner, and provide a replay workflow with audit notes.

How to monitor n8n workflows in production?

Track success rate, latency, retries, queue depth, cost, and business counters, then alert only when action is required.