Error Handling That Actually Catches Errors

The trap I see teams fall into is treating error handling as an afterthought they can solve with a single Slack node. They add Retry on Fail to the HTTP Request node, route failures to a chat channel, and call the system resilient. It works in the demo. Then, in production, a webhook payload shape changes silently, the workflow processes garbage for six hours, and the only sign of trouble is a string of timeout alerts from an unrelated API call that was never the root cause.

Real error handling is architectural. It covers the unexpected 502, the invalid business object, the batch item that fails, and the alert channel that got archived. It requires a central nervous system, deliberate guardrails, and a ruthless standard for signal versus noise.

Build the Error Hub First

I do not build error handling into individual workflows anymore. I build one Error Hub workflow and point every production workflow at it. The setting is in the workflow settings panel, under Error Workflow. It takes thirty seconds to configure and prevents silent failures from going unnoticed for days.

The Error Hub starts with an Error Trigger node. When any workflow crashes, n8n sends it a payload containing the execution ID, the workflow name, the last node executed, the full error message, and a direct URL back to the execution log. That payload is the difference between a panic and an investigation.

Inside the Error Hub, I use a Code node to parse that payload and assign severity. Not all errors are equal. A 502 from a CRM lookup at 2 a.m. is different from a "total mismatch" on a payment workflow at 2 p.m. I keep a hardcoded list of critical workflow names — Order Processing, Payment Handler, User Auth — and a list of warning patterns like rate limit, timeout, 503, and 429. Everything else is info.

// Code node: "Parse Error and Assign Severity"
const errorData = $input.first().json;
const workflowName = errorData.workflow?.name || 'Unknown Workflow';
const errorMessage = errorData.execution?.error?.message || 'No error message';
const lastNode = errorData.execution?.lastNodeExecuted || 'Unknown node';
const executionId = errorData.execution?.id;
const executionUrl = errorData.execution?.url;

let severity = 'info';
const criticalWorkflows = ['Order Processing', 'Payment Handler', 'User Auth'];
const warningPatterns = ['rate limit', 'timeout', '503', '429'];

if (criticalWorkflows.some(w => workflowName.includes(w))) {
  severity = 'critical';
} else if (warningPatterns.some(p => errorMessage.toLowerCase().includes(p))) {
  severity = 'warning';
}

return [{
  json: {
    severity,
    workflowName,
    errorMessage,
    lastNode,
    executionId,
    executionUrl,
    slackMessage: [
      `*Workflow Error [${severity.toUpperCase()}]*`,
      `*Workflow:* ${workflowName}`,
      `*Node:* ${lastNode}`,
      `*Error:* ${errorMessage}`,
      `*Execution:* <${executionUrl}|#${executionId}>`
    ].join('\n')
  }
}];

After the Code node, a Switch routes by severity. Critical hits PagerDuty and a dedicated incidents channel. Warning hits Slack. Info writes to a log table. When I need to add a new channel — say, a Telegram bot for critical alerts — I change one workflow, not thirty.

If your team is still adding notification nodes to the end of every workflow, you are one channel rename away from silent failures.

Halt on Bad Data, Not Just Bad Luck

The Error Hub catches unexpected crashes, but some errors are not crashes. They are invalid states that should never proceed. For those, I use the Stop and Error node as a guardrail.

Place it after validation logic. For example, an invoice processing workflow receives a webhook, sums the line items, and compares that sum to the stated total. If they do not match, something is fundamentally wrong with the source data. Continuing means posting bad numbers to the accounting system. I halt immediately.

# Stop and Error node settings
Error Type: Workflow
Error Message: >
  Invoice validation failed for invoice {{ $json.invoice.invoice_id }}:
  total mismatch (stated {{ $json.invoice.total }}, calculated {{ $json.calculatedTotal }}).
  Customer: {{ $json.invoice.customer_id }}.

The message surfaces in the execution log, in the Error Hub notification, and in any webhook response if I am using Respond to Webhook. It is unambiguous. It is searchable. It is not a stack trace.

I use Stop and Error at every boundary where invalid state should block progress: missing required fields after a webhook, failed schema validation before a database write, business rule violations.

Retry with Backoff, and When to Leave It Off

External APIs fail transiently. Network glitches, rolling deploys, and momentary rate limits are normal. I enable Retry on Fail on every node that calls an external API, but I treat the configuration as a policy decision, not a checkbox.

My defaults are simple:

If the API supports idempotency keys, I use them, then enable retries. If it does not, the retry setting stays off. There is no middle ground. A retry on a non-idempotent operation is not recovery logic; it is a self-inflicted incident.

Dead-Letter Queues as a First-Class Primitive

Some failures are expected. When I process a batch of 200 leads through a company enrichment API, five of those companies might return 404s. I do not want to kill the other 195. I enable Continue on Fail on the enrichment node.

The output of a Continue-on-Fail node changes. Failed items include an error object in their JSON. I route all items into a Code node that splits the stream: successes go forward, failures go to the Dead-Letter Queue.

// Code node: "Prepare DLQ Entry"
const failedItems = $input.all();

return failedItems.map(item => ({
  json: {
    dlq_id: `DLQ-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`,
    created_at: new Date().toISOString(),
    workflow_name: $workflow.name,
    execution_id: $execution.id,
    source_node: 'Enrich Company Data',
    original_payload: JSON.stringify(item.json),
    error_message: item.json.error?.message || 'Unknown error',
    error_code: item.json.error?.statusCode || null,
    status: 'pending',
    retryable: item.json.error?.message?.includes('429')
      || item.json.error?.message?.includes('500'),
    assigned_to: null,
    resolution_notes: null
  }
}));

For high-volume pipelines, I write these to a Postgres table with indexes on status and created_at. Google Sheets works for lighter loads, but Postgres scales and lets me query efficiently.

CREATE TABLE dead_letter_queue (
  id SERIAL PRIMARY KEY,
  dlq_id TEXT UNIQUE NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  workflow_name TEXT NOT NULL,
  execution_id TEXT,
  source_node TEXT,
  original_payload JSONB NOT NULL,
  error_message TEXT,
  error_code INTEGER,
  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'investigating', 'resolved', 'ignored')),
  retryable BOOLEAN DEFAULT false,
  retry_count INTEGER DEFAULT 0,
  assigned_to TEXT,
  resolved_at TIMESTAMPTZ,
  resolution_notes TEXT
);

CREATE INDEX idx_dlq_status ON dead_letter_queue(status);
CREATE INDEX idx_dlq_created ON dead_letter_queue(created_at);

Then I build a separate reprocessor workflow. It runs on a schedule, selects rows where status = 'pending' and retryable = true, parses original_payload back into JSON, runs the original processing logic via an Execute Workflow node or direct copy, and updates the row to resolved or investigating.

The Alert-Fatigue Test

The Error Hub can route alerts, but alerts are only useful if humans act on them.

A single 502 from a CRM API at 3 a.m. is not a pageable event. It is a line in a log. A batch failure where 47 out of 10,000 records fail due to invalid email formats is not 47 Slack messages; it is one daily digest with a link to the DLQ. A payment workflow failure is a page. Knowing the difference is the job of the routing logic in the Error Hub.

To catch the case where the Error Hub itself breaks — or was never set on a new workflow — I run a scheduled health-check workflow. It queries the n8n API for failed executions in the last hour, groups them by workflow, and sends a summary to a monitoring channel. If the Error Hub is silent but the health check shows failures, I know the safety net has a hole.

// Code node: "Query n8n API for Failed Executions"
const baseUrl = $env.N8N_HOST || 'http://localhost:5678';
const apiKey = $env.N8N_API_KEY;

const response = await this.helpers.httpRequest({
  method: 'GET',
  url: `${baseUrl}/api/v1/executions`,
  headers: { 'X-N8N-API-KEY': apiKey },
  qs: {
    status: 'error',
    limit: 100,
    startedAfter: new Date(Date.now() - 60 * 60 * 1000).toISOString()
  }
});

const byWorkflow = {};
for (const exec of response.data || []) {
  const name = exec.workflowData?.name || 'Unknown';
  byWorkflow[name] = (byWorkflow[name] || 0) + 1;
}

return [{
  json: {
    totalFailures: response.data?.length || 0,
    byWorkflow,
    checkTime: new Date().toISOString()
  }
}];

If the total is zero, the workflow sends nothing. If there are failures, it posts a concise summary. This is the safety net for the safety net.

Test Your Error Paths Like You Test Your Happy Paths

Error handling rots faster than business logic. Credentials expire. Slack channels get archived. Team members change their notification preferences. The only way to know it still works is to break it on purpose.

Once a quarter, I run an error fire drill. I temporarily change an API credential to an invalid key, trigger the workflow, and verify the Error Hub routes the notification to the right channel with a readable message. I feed a deliberately bad record into a batch workflow to confirm it lands in the DLQ with all triage fields populated. I point a test HTTP Request node at httpstat.us/500 and watch the retry intervals to confirm they match the policy. Then I fix what I broke.

What to Do Monday Morning

The goal is not perfect uptime; it is fast, observable recovery.