n8n Error Handling

Non-negotiables

Respond to Webhook

1. Every fallible node's error output is wired, and both paths end at a

   Respond to Webhook

   . No hanging error branches, or the caller would see a timeout. "Fallible" = HTTP, DB, third-party API, file operation, anything that throws.
2. Status code maps to cause. Caller's fault → 4xx, your fault → 5xx. A 200 default on an error path produces silent failure: caller thinks success, processes empty data.

1. Configure a workflow-level error workflow. Catches what escapes per-node handling: timeouts, crashes between nodes, errors in unwired nodes. See

   references/ERROR_WORKFLOWS.md

   . Currently, only the user can set error workflows through the UI in the workflow settings.

Strong defaults

• Error response bodies are structured. Not just "Internal Server Error". Use

  { "error": "<short identifier>", "message": "<human-readable>" }

  . See

  references/RESPONSE_SHAPES.md

  .
• Network-calling nodes have

  retryOnFail

  configured. Transient 429s and upstream blips get absorbed before reaching the error path. See "Self-healing on transient failures" below.

When error handling can be looser

onError: 'stopWorkflow'

API workflow shape

Webhook trigger
  ├── (success path)  → Process → Respond to Webhook (200, body)
  └── (any node's error output)
                       → Respond to Webhook (5xx, structured error body)
                       → Optional: log to error tracker / logger / notify channel

references/API_WORKFLOWS.md

Schema validator (Set IIFE)

• references/examples/validation-subworkflow.ts

  : the bare pattern (Webhook → Set with the validation IIFE → Respond, expression-driven status code). Useful as a minimal demo.

• references/examples/validation-subworkflow-usage.ts

  : the endpoint pattern (Webhook → Set → If valid → your business logic → 200 success / 400 with the standard

  {error: "validation_error", message, details, request_schema}

  body). Lift this into your endpoint and replace the NoOp placeholder with real logic.

1. Lift the usage-example structure into the new endpoint. Webhook → Set (Validate Schema) → If Params Valid → your logic → success/400 Respond. Don't reinvent.
2. Edit the IIFE for your schema. Update

   REQUIRED_SCHEMA

   and the per-field checks inside the Set node's expression for your endpoint's input shape. The pattern below the schema constant is mechanical: presence check, type check, constraint check, push to

   errors[]

   .
3. Leave the output shape alone.

   valid

   ,

   validationError

   ,

   details

   ,

   requiredSchema

   are the contract the Respond node consumes. Renaming them breaks the response body.

={{ ... }}

references/API_WORKFLOWS.md

Per-node error setup (recap)

n8n-connections

ERROR_OUTPUTS.md

1. Set

   onError: 'continueErrorOutput'

   on the node config.
2. Wire

   output(1)

   to your error handler.

Self-healing on transient failures

{
    retryOnFail: true,
    maxTries: 3,
    waitBetweenTries: 5000,    // ms; 5000 is the max and should be your default
}

maxTries

waitBetweenTries

packages/core/src/execution-engine/workflow-execute.ts

n8n-node-configuration

HTTP_NODES.md

AI_NODES.md

Response shapes: map the cause to the status code

text/plain "Internal Server Error"

Respond to Webhook

validation_error

references/examples/validation-subworkflow.ts

validation-subworkflow-usage.ts

unauthorized

forbidden

not_found

conflict

rate_limit_exceeded

Retry-After

internal_error

upstream_error

service_unavailable

upstream_timeout

• Validation failures (4xx) are checked upstream of the work, via IF/Switch branches, not error outputs. Use a dedicated Respond per shape (400 missing field, 401 no auth, etc.).
• Execution failures (5xx) come out of error outputs ("we tried, something broke"). A single error responder for all 5xx is fine. Differentiate the body's

  error

  code by inspecting the failed node where useful.

Response Code

// Response Code on a single Respond to Webhook node:
{{ (() => {
    const msg = $json.error?.message || $json.message || ''
    if (msg.includes('INVALID_ID')) return 400
    if (/429|too many/i.test(msg)) return 429
    if (/openrouter|anthropic|llm/i.test(msg)) return 502
    return 500
})() }}

references/RESPONSE_SHAPES.md

Workflow-level error workflows

1. Captures the failure (workflow name, execution ID, error, stack).
2. Notifies someone (Slack, email, on-call).
3. Optionally enqueues a retry (with backoff).

references/ERROR_WORKFLOWS.md

Reference files

references/API_WORKFLOWS.md

references/ERROR_WORKFLOWS.md

references/RESPONSE_SHAPES.md

Anti-patterns

output(1)

{ "error": ... }

onError: 'continueErrorOutput'

ERROR_WORKFLOWS.md

RESPONSE_SHAPES.md

retryOnFail

retryOnFail: true, maxTries: 3, waitBetweenTries: 5000

Response Code