برای مدیریت خطا در n8n و ساخت ورک فلوهای پایدار، سه کار را همزمان انجام دهید: 1) روی نودهای مستعد خطای موقتی مثل HTTP و OpenAI گزینه Retry On Fail را با محدودیت منطقی فعال کنید؛ 2) یک Error Workflow بسازید که با Error Trigger هر خطا را دریافت، لاگ و اعلان کند؛ 3) بدنه درخواست ها را به جای متن خام به صورت آبجکت بسازید یا با JSON.stringify سریال کنید تا کاراکترهایی مثل کوتیشن درخواست را خراب نکند. این ترکیب ساده، ستون فقرات «مدیریت خطا در n8n» است.

Error Trigger و Retry On Fail دقیقا چه می کنند؟

Retry On Fail تلاش خودکار مجدد در همان نود است و برای خطاهای موقتی مانند تایم اوت شبکه، خطاهای 5xx یا محدودیت نرخ مناسب است. Error Trigger یک تریگر اختصاصی در یک ورک فلو جداگانه است که وقتی اجرای ورک فلو دیگر به خطا می خورد، با تمام جزییات همان خطا اجرا می شود و به شما امکان می دهد لاگ بگیرید، اعلان بفرستید یا اقدامات جبرانی انجام دهید. اگر می خواهید جریان اصلی متوقف نشود، می توانید در بعضی نودها Continue On Fail را روشن کنید؛ اما این کار فقط زمانی مفید است که خروجی خطا را بعدا به درستی مدیریت کنید.

الگوی پیشنهادی برای ورک فلوهای پایدار

  1. طبقه بندی خطا: قبل از هر چیز مرز بین خطای موقتی و دائمی را روشن کنید.
    • موقتی: 408، 429، 5xx، قطع موقت شبکه، پاسخ ناقص مدل هوش مصنوعی. راهکار: Retry On Fail با فاصله زمانی.
    • دائمی: 400، 401، 403، 404 یا اعتبارسنجی ناموفق داده. راهکار: Fail Fast و ارسال به Error Workflow برای پیگیری.
  2. فعال کردن Retry On Fail در نودهای حساس: روی HTTP Request، OpenAI و هر نودی که به سرویس بیرونی وصل است، Retry On Fail را فعال کنید. تعداد تلاش و فاصله زمانی را منطقی تنظیم کنید تا هم تاب آوری بالاتر برود و هم صف اجرا قفل نشود.
  3. ساخت Error Workflow با Error Trigger:
    1. یک ورک فلو جدید بسازید و نود Error Trigger را اضافه کنید.
    2. در ورک فلوهای اصلی، از تنظیمات Workflow گزینه Error Workflow را روی همین ورک فلو ست کنید.
    3. بعد از Error Trigger با یک Set یا Function داده هایی مانند نام ورک فلو، نام نود، پیام خطا و ورودی آخرین نود را شکل دهید و سپس آن را به مقصدی برای لاگ و اعلان بفرستید (مثلا ایمیل، چت تیمی یا ذخیره در دیتابیس).
  4. اعتبارسنجی ورودی و Fail Fast: قبل از فراخوانی های گران یا حساس، با If یا Function داده را چک کنید و در صورت ناسالم بودن، عمدا خطا پرتاب کنید تا به Error Workflow هدایت شود.

مثال عملی: ارسال محتوا به یک API بدون شکستن JSON

در بررسی ورک فلو انتشار مقاله کدیتی مشخص شد درج مستقیم متن در بدنه JSON نود HTTP Request باعث می شود یک کاراکتر کوتیشن کل درخواست را خراب کند و چون Error Workflow فعال نبود، خطا بی صدا رخ می داد. دو راه امن برای حل:

راه امن A: ارسال بدنه به صورت آبجکت

  1. در HTTP Request گزینه ارسال بدنه را روی JSON قرار دهید.
  2. فیلدهای بدنه را به صورت آبجکت بسازید و از Expression ها برای تزریق متن استفاده کنید. n8n به شکل امن کاراکترها را escape می کند.
{
  "title": "{{$json.title}}",
  "content": "{{$json.content}}",
  "status": "publish"
}

این روش حتی اگر content شامل کوتیشن یا کاراکترهای خاص باشد، JSON معتبر تولید می کند.

راه امن B: اگر مجبورید RAW بفرستید

اگر طرف مقابل فقط RAW می پذیرد، بدنه را قبل از ارسال سریال کنید:

// Function یا Set برای ساخت رشته JSON امن
const body = {
  title: $json.title,
  content: $json.content,
  status: 'publish',
};
return [{ json: { rawBody: JSON.stringify(body) } }];

سپس در HTTP Request حالت RAW را انتخاب کنید و Body را روی {{$json.rawBody}} بگذارید.

فعال کردن Retry On Fail برای API های ناپایدار

برای نودهای OpenAI و HTTP که به سرویس بیرونی وصل اند، Retry On Fail را روشن کنید تا خطاهای 429 یا تایم اوت با چند تلاش مجدد پایدار شوند. برای خطاهای 400 یا 403 Retry را خاموش بگذارید تا به سرعت به Error Workflow بروید.

نمونه های کوتاه از اعتبارسنجی و خطا دهی کنترل شده

اعتبارسنجی قبل از فراخوانی API:

// Function node
if (!$json.slug || !$json.title) {
  throw new Error('عنوان یا اسلاگ خالی است');
}
return items;

این خطا به طور خودکار اجرای جاری را متوقف می کند و Error Workflow را با اطلاعات کامل اجرا می کند.

چه چیزی را به Error Workflow بفرستیم؟

  • متادیتای اجرا: شناسه اجرا، نام ورک فلو و نام آخرین نود.
  • جزئیات خطا: پیام خطا، نوع خطا و تا حد امکان وضعیت HTTP.
  • نمونه داده ورودی: بخش های غیرحساس داده برای تکرارپذیری مشکل.
  • شدت و اقدام بعدی: severity مانند info/warn/error و پیشنهاد اقدام دستی.

اگر برای تیم محصول داشبورد می سازید، طراحی یک Error State واضح به کشف سریع ریشه مشکل کمک می کند. برای ایده های طراحی وضعیت های خطا می توانید راهنمای طراحی Empty State و Error State در داشبوردها را ببینید.

سیاست Retry معقول چیست؟

پاسخ کوتاه: برای خطاهای 408، 429 و 5xx یا مشکلات شبکه Retry با فاصله زمانی معقول انجام دهید و برای خطاهای 4xx (به جز 408 و 429) Retry را متوقف کنید.

  • حداکثر چند تلاش محدود تعریف کنید تا صف اجرا قفل نشود.
  • بین تلاش ها فاصله بگذارید تا از کوبیدن سرویس مقصد جلوگیری شود.
  • Retry فقط وقتی ارزش دارد که احتمال بهبود خودکار وجود داشته باشد.

اشتباهات رایج و راه درست

  • نوشتن بدنه JSON به صورت متن خام: منجر به شکستن درخواست با یک کوتیشن می شود. راه درست: ساخت بدنه به صورت آبجکت یا JSON.stringify.
  • Retry برای خطای دائمی: زمان را هدر می دهد و صف را سنگین می کند. راه درست: Fail Fast و ارسال به Error Workflow.
  • نداشتن Error Workflow: خطاها بی صدا گم می شوند. راه درست: یک Error Workflow مشترک بسازید و آن را روی همه ورک فلوهای مهم ست کنید.
  • Continue On Fail بدون مدیریت خروجی: خطا در سکوت ادامه پیدا می کند. راه درست: اگر روشن است، شاخه خطا را واقعا مدیریت کنید.

چک لیست سریع قبل از انتشار

  • برای نودهای بیرونی: Retry On Fail با محدودیت منطقی فعال است؟
  • برای هر ورک فلو مهم: Error Workflow ست شده است و Error Trigger پیام را دریافت می کند؟
  • ورودی و بدنه درخواست ها: آبجکت امن یا JSON.stringify شده هستند؟
  • اعتبارسنجی پیش از فراخوانی های گران: انجام می شود و در صورت ناسالم بودن Fail Fast می کنید؟
  • تقسیم پذیری خطاها: سیاست جداگانه برای 4xx در برابر 5xx دارید؟

ارتباط با ایجنت های هوش مصنوعی

ایجنت های هوش مصنوعی در n8n معمولا چندین تماس پیاپی با مدل و API های بیرونی دارند. ترکیب Retry On Fail و Error Workflow جلوی توقف ناگهانی سناریوهای چندمرحله ای را می گیرد و امکان جبران یا ادامه ایمن را فراهم می کند. اگر تازه با ساخت ایجنت در n8n شروع کرده اید، آموزش آموزش ساخت ایجنت هوش مصنوعی با n8n برای پاسخ گویی خودکار نقطه شروع خوبی است. برای درک الگوهای جبرانی در سناریوهای چندمرحله ای هم سر زدن به Saga Pattern در میکروسرویس: مدیریت تراکنش های توزیع شده مفید است.

گام بعدی چیست؟

یک Error Workflow مشترک بسازید، آن را روی همه ورک فلوهای اصلی ست کنید و روی نودهای HTTP و OpenAI سیاست Retry معقول تعریف کنید. سپس با یک Function عمدا خطا پرتاب کنید تا مسیر اعلان و لاگ را محک بزنید. اگر با ابزارهای AI کار می کنید، گذراندن یک دوره آموزش ابزارهای هوش مصنوعی به استانداردسازی این سیاست ها در همه سناریوها کمک می کند.