n8n-error-handling-official

n8n のエラー処理

n8n ノードのデフォルトの動作：エラー → ワークフローが停止 → 呼び出し元には役立つ情報が何も返りません。Webhook API、スケジュール済みジョブ、キューワーカーなど、無人で実行するワークフローでは、このデフォルトの動作は適切ではありません。「連携が突然動かなくなった」という症状が出ても、ログもメッセージも手がかりもありません。

このスキルでは、エラーを目立つ形で構造化し、復旧可能にするための処理方法を説明します。最善の場合は、自己修復する形で処理します。

必須事項

API 型のワークフロー（Webhook トリガーと Respond to Webhook を組み合わせたもの）では、次の事項を守ってください。

1. エラーが発生する可能性のあるすべてのノードのエラー出力を接続し、どちらの経路も Respond to Webhook で終わるようにします。 エラー分岐を宙ぶらりんにすると、呼び出し元がタイムアウトします。「エラーが発生する可能性のあるノード」とは、HTTP、DB、サードパーティ API、ファイル操作など、エラーを発生させるものを指します。
2. ステータスコードを原因に対応させます。 呼び出し元の問題なら 4xx、こちら側の問題なら 5xx です。エラー経路でデフォルトの 200 を返すと、呼び出し元は成功したと思い、空のデータを処理してしまうため、エラーが表面化しません。

無人で実行するワークフロー（スケジュール、cron、キュー駆動、エージェントツール）では、さらに次の事項を守ってください。 3. ワークフロー単位のエラーワークフローを設定します。 ノード単位の処理から漏れたタイムアウト、ノード間のクラッシュ、未接続ノードのエラーを捕捉します。update_workflow の setWorkflowSettings.errorWorkflow を使って設定してください（n8n 2.29.0 以降）。対象となるワークフローは公開済みで、アクティブな Error Trigger を含んでいる必要があります。そうでない場合、更新は拒否されます。references/ERROR_WORKFLOWS.md を参照してください。

強く推奨するデフォルト設定

• エラーレスポンスの本文は構造化します。 「内部サーバーエラー」だけにしないでください。{ "error": "<short identifier>", "message": "<human-readable>" } を使用します。references/RESPONSE_SHAPES.md を参照してください。
• ネットワーク通信を行うノードには retryOnFail を設定します。 一時的な 429 や上流の一時的な障害は、エラー経路に到達する前に吸収します。以下の「一時的な障害からの自己修復」を参照してください。

エラー処理を緩和できる場合

自分だけが使い、実行のたびに確認し、失敗しても「気づいて再実行する」だけで済む、内部向けの単発ワークフローです。デフォルトの onError: 'stopWorkflow' で問題ありません。自分以外の誰かが出力を見る場合（後続システム、エンドユーザー、オンコール担当者）は、必須事項を適用します。

API ワークフローの構成

標準的な Webhook API ワークフロー：

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

複数のエラーが発生する可能性のあるノードを 1 つのエラーレスポンダーに接続する方法を含む詳しい手順は、references/API_WORKFLOWS.md を参照してください。

スキーマバリデーター（Set IIFE）

入力検証を行う Webhook API では、フィールドごとに IF/Switch チェーンを書くのではなく、Set ベースのスキーマバリデーターパターンをエンドポイントに取り入れてください。次の 2 つのサンプルファイルが正となる情報源です。

• references/examples/validation-subworkflow.ts：基本パターン（Webhook → Set の検証 IIFE → Respond、ステータスコードは式で制御）。最小限のデモとして役立ちます。
• references/examples/validation-subworkflow-usage.ts：エンドポイントのパターン（Webhook → Set → 有効な場合は If → ビジネスロジック → 200 成功レスポンス／標準の {error: "validation_error", message, details, request_schema} 本文を含む 400）。これをエンドポイントに取り入れ、NoOp プレースホルダーを実際のロジックに置き換えてください。

これを使用するエージェントの手順：

1. 使用例の構成を新しいエンドポイントに取り入れます。 Webhook → Set（スキーマの検証）→ If Params Valid → ロジック → 成功／400 Respond。独自に作り直さないでください。
2. IIFE をスキーマに合わせて編集します。 エンドポイントの入力形式に応じて、REQUIRED_SCHEMA と Set ノードの式内のフィールドごとのチェックを更新します。スキーマ定数以下のパターンは機械的なもので、存在チェック、型チェック、制約チェックを行い、errors[] に追加します。
3. 出力形式は変更しないでください。 valid、validationError、details、requiredSchema は Respond ノードが使用する契約です。名前を変更するとレスポンス本文が壊れます。

詳細な手順、サポートされている制約パターン、スキーマ設計ルール、および ={{ ... }} のラップに関する注意点は、references/API_WORKFLOWS.md の「スキーマバリデーター（Set IIFE）」を参照してください。

ノードごとのエラー設定（再確認）

エラーが発生する可能性のある各ノードには、2つの変更が必要です（references/NODE_ERROR_OUTPUTS.mdを参照）。

1. ノード設定でonError: 'continueErrorOutput'を設定します。
2. output(1)をエラーハンドラーに接続します。

どちらも必須です。片方だけでは、エラーが通知されない状態になります。

一時的な障害に対する自己修復

エラーパスを接続する前に、ネットワーク呼び出しを行うすべてのノード（HTTP Request、Gmail／Slack／Discordなどの通信、DB、AI、サードパーティ API のノード）でノードレベルの再試行を設定してください。一時的な429や上流サービスの短時間の障害を吸収できるため、エラー出力は実際の障害が発生した場合にのみ実行され、アラートや5xxレスポンスもノイズではなく実際の問題を反映します。

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

HTTP Requestに限らず、ネットワークサービスを呼び出すすべてのノードで機能します。エンジンはステータスコードによるフィルターを設けず、あらゆるエラーで再試行します。また、エンジンではmaxTriesの上限を5、waitBetweenTriesの上限を5000msに設定しています（packages/core/src/execution-engine/workflow-execute.ts）。ノード固有の注意事項については、n8n-node-configuration-officialのHTTP_NODES.mdおよびAI_NODES.mdを参照してください。

レスポンス形式：原因に応じてステータスコードを割り当てる

text/plain "Internal Server Error" を含む 5xx レスポンスは、技術的には 5xx ですが、役に立ちません。また、すべてのエラーが 5xx とは限りません。リクエストが失敗した 原因 に応じて、ステータスコードを使い分けてください。

よくある間違い： すべてのエラーパスを、500「internal_error」を返す単一の Respond to Webhook に接続することです。送信された入力が不正な場合でさえ、呼び出し元にはすべての失敗が同じように見えます。実際の障害と呼び出し元の入力ミスを区別できないため、監視にも支障が出ます。

原因ごとのデフォルトのマッピング：

原因	ステータス	エラーコード	経路
必須フィールドがない、または型が異なる	400	validation_error	Set ベースのスキーマバリデーターで事前に検証します（基本パターンについては references/examples/validation-subworkflow.ts、エンドポイントのテンプレートについては validation-subworkflow-usage.ts を参照）。単純なケースでは、インラインの IF/Switch と専用の 400 を返す Respond を使用します。エラー出力は経由しません。理想的には、呼び出し元が自分で修正できるよう、レスポンスにスキーマを含めます。
認証情報がない、または無効	401	unauthorized	同様です。事前にチェックし、401 を直接返します。
認証済みだが許可されていない	403	forbidden	同様です。
リクエストにリソース ID があるが、データ内に存在しない	404	not_found	ルックアップのエラーではなく、ルックアップ結果から分岐します。
現在の状態と操作が競合する（重複、競合状態）	409	conflict	エラー出力ではなく、ロジックで検出します。
呼び出し元がレート制限を超過した	429	rate_limit_exceeded	Retry-After ヘッダーを設定します。
ノードで例外が発生し、原因がわからない	500	internal_error	エラー出力の経路です。
サードパーティ API でエラーが発生した	502	upstream_error	HTTP Request ノードのエラー出力です。
ワークフローが現在処理できない（下流が停止中、上流がレート制限中）	503	service_unavailable	特定のエラーを検出し、ヒントとともに返します。
サードパーティ API がタイムアウトした	504	upstream_timeout	エラーメッセージでフィルタリングしたエラー出力です。

異なる 2 つのフロー：

• 検証エラー（4xx） は、エラー出力ではなく、IF/Switch 分岐を使って処理の 前段 でチェックします。各レスポンス形式に専用の Respond を使います（400 はフィールド不足、401 は認証なしなど）。
• 実行エラー（5xx） は、エラー出力から発生します（「処理を試みたが、何かが壊れた」）。すべての 5xx に対して単一のエラーレスポンダーを使っても問題ありません。必要に応じて、失敗したノードを調べ、本文の error コードを使い分けます。

Respond は 1 つ、ステータスコードは式で指定。 エラーパスの違いがステータスコードとメッセージテキストだけの場合（本文の形式が同じで、ヘッダーやコンテンツタイプも変わらない場合）、Switch で N 個の Respond ノードに分岐させないでください。Respond to Webhook ノードの Response Code と本文のフィールドには式を指定できます。コードをインラインで計算すれば、1 つの Respond ノードでエラーパス全体を処理できます。

// 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
})() }}

レスポンスの構造が 異なる 場合に限り、Switch と N 個の Respond に分岐させる意味があります。たとえば、ヘッダー、本文の形式、リダイレクト、コンテンツタイプが異なる場合です。形式が同じで数値だけが異なる場合は、式で指定する Respond を 1 つ使います。

相関 ID、再試行可能か致命的かを示すフラグ、検証の詳細、レート制限の形式など、規約の全容については、references/RESPONSE_SHAPES.md を参照してください。

ワークフローレベルのエラーワークフロー

無人で実行するワークフローでは、インスタンスのエラーワークフロー（またはワークフロー単位の上書き先）として、次の処理を行うワークフローを設定します。

1. 失敗の情報を取得します（ワークフロー名、実行 ID、エラー、スタック）。
2. 関係者に通知します（Slack、メール、オンコール）。
3. 必要に応じて、再試行をキューに追加します（バックオフあり）。

ノード単位の処理では見逃す、タイムアウト、ノード間のクラッシュ、接続されていないノードのエラーを捕捉します。

references/ERROR_WORKFLOWS.md を参照してください。

参照ファイル

ファイル	読むタイミング
references/API_WORKFLOWS.md	Webhook トリガー／Webhook 応答ワークフローを構築またはレビューするとき
references/ERROR_WORKFLOWS.md	本番ワークフローでワークフローレベルのエラー捕捉を設定するとき
references/RESPONSE_SHAPES.md	API のレスポンスボディの規約を定義するとき
references/NODE_ERROR_OUTPUTS.md	個々のエラーが発生しうるノードにノード単位のエラー出力を接続するとき

アンチパターン

アンチパターン	問題点	修正方法
Webhook → 処理 → 応答で、エラーブランチがない	呼び出し元がタイムアウトまたは空の 500 を受け取ります	エラーが発生しうるすべてのノードの output(1) を Respond to Webhook に接続します
どちらのパスにも単一の Respond to Webhook を使用する	ボディの形式から呼び出し元が何が起きたのか判断できません	パスごとに Respond ノードを 1 つずつ配置し、明示的なコードとボディを設定します
エラーパスが { "error": ... } ボディで 200 を返す	呼び出し元の HTTP クライアントは成功として扱うため、エラー処理が実行されません	エラーパスでは必ず 4xx／5xx を返します
Code ノードでエラーを捕捉し、データとして返す	後続ノードにはエラー形式のデータが渡され、ワークフローが続行します	エラーをスローさせ、onError: 'continueErrorOutput' を設定してエラーパスを接続します
ワークフローレベルのエラーワークフローがない本番ワークフロー	実際の障害がどこにも通知されません	エラーワークフローを設定します。ERROR_WORKFLOWS.md を参照してください
すべての失敗に汎用的な「Internal Server Error」を返す	呼び出し元の不具合、上流の障害、レート制限を区別できません	構造化されたエラーコードを使用します。RESPONSE_SHAPES.md を参照してください
本番ノードが、不安定またはレート制限のある API を retryOnFail なしで呼び出す	一時的な 429 や上流の瞬断がすべて 5xx として表面化し、ノイズでアラートが発火します	ノードに retryOnFail: true, maxTries: 3, waitBetweenTries: 5000 を設定します。「一時的な障害からの自己回復」を参照してください
200 以外はすべて 500 にする	呼び出し元は入力の不備とサービスの障害を区別できず、ノイズで監視アラートが発火します	原因に応じてステータスコードを割り当てます。呼び出し元に起因する問題には 4xx を使用します
エラーメッセージで分岐し、ステータスコードだけが異なる N 個の Respond ノードを配置する	式で制御する Response Code を使った単一の Respond で済むところに、5 個のノードが必要になります	単一の Respond 内で式を使ってコードを計算します。上記の「1 つの Respond で式を使ってステータスコードを指定」を参照してください