The n8n Error Handling Playbook: Retries, DLQs, Circuit Breakers, and Replay

Every workflow you'll ever build in n8n fails in exactly one of three ways: transient (network blip, 429, timeout, brief provider hiccup), semantic (bad input, missing record, schema drift, business-rule violation), or systemic (auth expired, quota exhausted, provider outage, database down). Treating them the same is the number-one cause of silent data loss and pager fatigue in n8n shops.

The rest of this playbook shows exactly how to implement each response inside n8n — with copy-paste patterns, Postgres schemas, and the exact dashboards to build.

Classification has to happen at the boundary between a workflow and the outside world — HTTP nodes, database nodes, LLM providers. Do it in a shared sub-workflow so every integration classifies the same way.

// classify.js — reusable Code node
const err = $json.error ?? {};
const status = err.status ?? err.statusCode ?? 0;
const message = (err.message ?? "").toLowerCase();

function classify() {
  if ([408, 425, 429, 500, 502, 503, 504].includes(status)) return "transient";
  if (status === 401 || status === 403) return "systemic"; // auth broken
  if (status === 402 || /quota|rate limit exceeded/i.test(message)) return "systemic";
  if (status >= 400 && status < 500) return "semantic";
  if (/econnreset|etimedout|socket hang up/i.test(message)) return "transient";
  return "systemic";
}
return [{ json: { ...$json, failureClass: classify() } }];

Route the output on failureClass into three branches: retry, dlq, breaker. Every workflow in the org uses this classifier — no branch, no invention.

n8n's built-in retry is fine for a few attempts on internal calls, but for anything customer-facing you want full-jitter exponential backoff. The math matters: without jitter, N clients that failed at the same time all retry at the same time and DDoS the recovering service.

// retry-delay.js — Code node inside a retry sub-workflow
const attempt = $json.attempt ?? 0;
const maxAttempts = 5;
const baseMs = 500;
const capMs = 30_000;

if (attempt >= maxAttempts) {
  return [{ json: { ...$json, giveUp: true } }]; // -> route to DLQ
}
// AWS-style full jitter
const upper = Math.min(capMs, baseMs * 2 ** attempt);
const delayMs = Math.floor(Math.random() * upper);
return [{ json: { ...$json, attempt: attempt + 1, delayMs } }];

Feed delayMs into a Wait node, then loop back into the flaky call. On giveUp, drop the payload into the DLQ described below. For payment providers, cap at 3 attempts and coordinate with their idempotency headers — retrying a charge without idempotency is how you double-bill customers.

Most teams create a dlq table, dump failures, and call it done. Six months later it has 400,000 rows, nobody knows what's replayable, and half the entries reference schemas that no longer exist. A real DLQ has four parts: schema, owner, replayer, and dedup key.

create table workflow_dlq (
  id uuid primary key default gen_random_uuid(),
  workflow_id text not null,
  execution_id text not null,
  dedup_key text not null,
  payload jsonb not null,
  error jsonb not null,
  failure_class text not null check (failure_class in ('transient','semantic','systemic')),
  attempts int not null default 0,
  owner_team text not null,
  created_at timestamptz not null default now(),
  replayed_at timestamptz,
  resolved_at timestamptz,
  unique (workflow_id, dedup_key) -- prevents floods on retry loops
);
create index on workflow_dlq (workflow_id, resolved_at) where resolved_at is null;

The dedup_key is what makes the DLQ safe. Pick something idempotent — order ID + step name, message ID + handler, webhook delivery UUID. Without it, a broken workflow that retries in a tight loop will insert 10k rows in an hour and mask the real errors.

The owner_team column matters more than it looks. On day one, every DLQ row must have a human who owns it. Without an owner, the queue becomes a graveyard nobody reviews.

The DLQ replayer is a small, boring, extremely important workflow. It runs on a schedule, pulls unresolved rows, re-enqueues them, and marks results. Because dedup_key is unique, replaying the same row twice is a no-op.

1. Cron trigger every 5 minutes → select up to 100 unresolved rows for the current workflow, oldest first.
2. For each row: increment attempts, call the target sub-workflow with the original payload.
3. On success → set resolved_at = now(). On failure → update error and re-classify.
4. If attempts > 10, stop retrying automatically and open a Linear/Jira ticket assigned to owner_team.

Expose a manual replay button in an internal admin tool (a tiny Next.js or n8n Webhook page) so on-call engineers can flush a batch after an upstream recovers, instead of waiting for the next cron tick.

When an upstream is down, retrying makes it worse: you burn your quota, extend the outage, and often trip the provider's abuse detection. A circuit breaker fixes this by refusing to call a known-dead service for T seconds.

Store the breaker in Redis (or a Postgres table with a for update skip locked read) as three states — closed, open, half-open:

• closed: requests pass through; consecutive failures increment a counter. At 5 failures in 60s, flip to open.
• open: every request short-circuits into the DLQ for T seconds (start at 30s, exponentially double on repeated flips).
• half-open: after T, allow exactly one probe. Success → closed. Failure → back to open with double T.

// breaker.js — Code node called before every risky HTTP request
const svc = $json.service;
const key = 'breaker:' + svc;
const state = await redis.hgetall(key);
const now = Date.now();

if (state.status === 'open' && Number(state.openedUntil) > now) {
  return [{ json: { ...$json, breaker: 'short-circuit' } }]; // -> DLQ
}
if (state.status === 'open') {
  await redis.hset(key, { status: 'half-open' });
}
return [{ json: { ...$json, breaker: 'pass' } }];

Retries are only safe when the target operation is idempotent. That means the same call, made N times, has the same effect as one call. Most APIs support this through an idempotency key header — use it or design around it.

For anything that touches money, users, or external systems, idempotency is not optional. Bake it in on day one — retrofitting is orders of magnitude more painful.

The goal is one dashboard that answers three questions in five seconds: is anything broken right now?, is anything drifting?, where do I look next?

1. Send execution.finished events from n8n to your logs pipeline (Loki, Datadog, BigQuery).
2. Tag every log line with workflow_id, execution_id, failure_class, and a business correlation ID (order ID, user ID).
3. Build a single Grafana/Metabase dashboard: success rate per workflow, p50/p95 duration, DLQ depth per owner, breaker state per integration.
4. Alert on rates of change, not absolutes — a 3× jump in DLQ depth in 10 minutes beats a fixed threshold at 500 rows.
5. Wire alerts to the same channel where the owner team already lives (a Slack per team, not one #alerts firehose).

You cannot claim reliability if you've never simulated failure. Bake three failure drills into your CI or a weekly Cron:

• Chaos node — a Code node that randomly throws with probability P. Turn P up to 1 in staging and confirm the DLQ fills correctly and the breaker opens.
• Latency injection — a Wait node with a random 0–30s delay in front of every external call. Confirms timeouts and downstream Wait/backoff paths.
• Provider outage — point a specific integration at a URL that returns 503. Confirm the breaker opens, the DLQ receives typed rows, and the replayer flushes on recovery.

None of these need to be fancy. Ten minutes of chaos in staging on Friday saves ten hours of forensic archaeology on Monday.

1. Wrap external calls in the shared classify sub-workflow.
2. Add the workflow_dlq table and route semantic + give-up cases into it.
3. Ship the replayer workflow with the 5-minute cron.
4. Introduce the breaker sub-workflow in front of every third-party integration.
5. Add Idempotency-Key headers to every money- or user-touching HTTP call.
6. Emit execution.finished events to your logs pipeline with rich tags.
7. Build the four-tile dashboard (success rate, p95, DLQ depth, breaker state).
8. Run a chaos drill: crank the classify test path to 50% failure, confirm nothing leaks.
9. Assign an owner_team to every workflow and route its alerts to that team's Slack.
10. Document the runbook in one Notion / Confluence page linked from the dashboard.