はじめに

精心に設計されたワークフローであっても、API呼び出しの失敗、不正なペイロード、タイムアウトにはいずれ直面します。本番環境では、そうした障害を検知し、ログに記録し、適切に処理する必要があります。サイレントに握り潰したり、実行全体をクラッシュさせたりしてはなりません。このレッスンでは、信頼性の高いn8nワークフローの3つの柱、つまり構造化されたエラー処理、実行ログによるデバッグ、そしてあらゆるインテグレーションに適用できるデプロイ前チェックリストを取り上げます。

n8nのエラーブランチ

n8nはエラーを検知するために、Error Triggerノードとノード単位のエラー出力という2つの主要な仕組みを提供します。

Error Triggerノードはワークフロー単位の検知機構です。Error Triggerノードのみをトリガーとする独立したワークフローを作成し、Settings > Error Workflowで本体ワークフローから参照します。本体ワークフローのいずれかのノードが未処理のエラーを発生させると、n8nは自動的にエラーワークフローを起動し、ワークフロー名、失敗したノード、エラーメッセージ、完全な実行IDを含むペイロードを渡します。

{
  "execution": {
    "id": "1042",
    "url": "https://your-n8n-instance/execution/1042",
    "retryOf": null,
    "error": {
      "message": "Request failed with status code 429",
      "stack": "..."
    },
    "lastNodeExecuted": "HTTP Request",
    "mode": "webhook"
  },
  "workflow": {
    "id": "7",
    "name": "Sync CRM Contacts"
  }
}

エラーワークフロー内では、このペイロードをSlack、PagerDuty、メールノード、データベースの行など、チームが監視している任意の宛先にルーティングできます。

より細かい制御が必要な場合は、各ノードのセカンダリ出力ピンを使用します。「Continue on Fail」を有効化するか、ノード単位のエラーブランチ（HTTP Request、Code、その他多くの連携ノードで利用可能）を有効化すると、このピンが表示されます。このピンを下流ノードに接続することで、ワークフロー全体を停止させることなく、失敗をインラインで処理できます。これは、バッチ内の単一アイテムの失敗をログに記録してスキップすべきで、すべてを中断すべきではない場合に適したパターンです。

実行ログを使った障害の追跡

n8nのすべての実行（成功・失敗問わず）はExecutionsパネルに保存されます。任意の実行を開くと、各ノードの正確な入力データと出力データを確認できるため、障害の追跡は容易です。

実践的なデバッグループは次のとおりです。ワークフローを実行し、失敗した実行を開き、赤いノードをクリックし、Outputタブを確認します。エラーメッセージと、それを発生させた入力データの両方がそこに表示されます。HTTP呼び出しの場合、生のレスポンスステータスとボディも表示されるため、一般的なエラー文字列よりもはるかに有用です。

内蔵のパネルだけでは不十分な場合（たとえば中間的な変換を検証したい場合など）は、入力をログに記録するだけの仮Codeノードを挿入します。

console.log(JSON.stringify($input.all(), null, 2));
return $input.all();

n8nは`console.log`の出力をノードの実行詳細画面に表示するため、データ連鎖の任意の時点でデータの正確な形状を確認できます。デプロイ前にこのノードは削除してください。

Webhookでトリガーされるワークフローの場合、「Listen for Test Event」ボタンを使って実際に入ってくるペイロードを捕捉し、開発中に繰り返し再実行すると便利です。これにより、外部システムを毎回トリガーし直す必要がなくなります。

リトライ設定とタイムアウト設定の適用

外部APIは一時的に失敗します。Code节点内で手動のリトライロジックを構築するのではなく、ノード単位で設定してください。任意のHTTP Requestノードで、ノード設定を開き、Max Retries（通常2〜3）とRetry Intervalを設定します。n8nは5xxレスポンスやネットワークエラーに対して自動的にバックオフし、リトライを行います。

必ず明示的なTimeout値を設定してください。既定値はタイムアウトなしであり、これはハングしたアップストリームサービスが無期限に実行スレッドをブロックし続けることを意味します。10000〜30 000ミリ秒の範囲であれば、ほとんどのREST APIに対応できます。

{
  "options": {
    "timeout": 15000,
    "retry": {
      "maxTries": 3,
      "waitBetweenTries": 2000
    }
  }
}

このJSONは、HTTP RequestノードUIで設定するoptionsオブジェクトを表しており、手書きするものではありませんが、ワークフローをJSONファイルとしてエクスポートおよびバージョン管理する際に基本構造を理解するうえで役立ちます。

デプロイ前チェックリスト

本番環境で任意のワークフローを有効化する前に、以下の項目を確認してください。

まず、ハードコードされたすべての認証情報とURLを、n8n Credentialsまたは`$env`オブジェクト経由でアクセスする環境変数に置き換えてください。シークレットをノードパラメータ内に平文文字列として記述してはいけません。

次に、すべての外部呼び出しにタイムアウトが設定されていること、必要に応じてリトライ設定があることをご確認ください。

続いて、Settingsから本番ワークフローにError Workflowを接続してください。故意にエラーをスローする仮Codeノードを追加してテストします。

throw new Error('Test error — remove before deploy');

Slackチャンネルやアラートシステムに通知が届くことを確認したら、仮ノードを削除します。

4番目に、実行モードを確認します。スケジュールまたはWebhookでトリガーされるワークフローでは、「Save Execution Progress」を有効化し、 crash時に部分的な進捗が失われないようにしてください。

第五に、保存内容を制限します。ワークフローが個人情報を処理する場合、データ保持ポリシーに応じて「Save Data Error Execution」と「Save Data Success Execution」を「Latest only」に設定するか、無効化してください。

まとめ

本番グレードのn8nワークフローには3つの習慣があります。エラーを握り潰すのではなく、Error Triggerやインラインのエラーブランチを使って明示的にルーティングすること、Executionsパネルと`console.log`を使ってデータ連鎖の任意の時点のデータを検査すること、認証情報、タイムアウト、アラート、データ保持を網羅する一貫したデプロイ前チェックリストを実施すること。これらのプラクティスは事前の手間を大きく増やすものではありませんが、深夜2時にデバッグに追われる状況をほぼ解消してくれます。