جلوگیری از اجرای تکراری در n8n

در n8n «اجرای دوباره» می‌تواند از چند راه رخ دهد: ارسال مجدد وب‌هوک از سمت فرستنده، Retry On Fail روی یک گره، تلاش مجدد دستی یک اجرای ناموفق، یا اجرای همزمان دو درخواست یکسان. اگر گردش‌کار شما پیامک می‌فرستد، سفارش می‌سازد یا پول جابه‌جا می‌کند، هر کدام می‌تواند اثر جانبی را دو بار ایجاد کند. این مقاله روش‌های طراحی‌شده برای جلوگیری از اجرای تکراری را مرور می‌کند: کلید ایدمپوتنسی، ثبت وضعیت، تلاش مجدد کنترل‌شده و صف خطا.

مرجع و نسخه: مستندات رسمی n8n در ۱۹ اکتبر ۲۰۲۶ (نسخهٔ پایدار ۲٫۴۳٫۷، بتا ۲٫۴۴٫۳) و مستندات Stripe و AWS خوانده شد. نمونه‌ها ساختگی‌اند و روی سیستم واقعی آزموده نشده‌اند. مثال‌های منطق (شبه‌کد) توصیهٔ نویسنده‌اند، نه نقل از مستندات. برای مفهوم API و ارتباط نرم‌افزارها API چیست را ببینید.

چرا تکرار رخ می‌دهد

فرستندهٔ وب‌هوک اگر پاسخ را به‌موقع نگیرد معمولاً دوباره می‌فرستد؛ n8n هم سه حالت پاسخ دارد (بلافاصله، پس از پایان آخرین گره، یا با گرهٔ Respond to Webhook) و انتخاب آن بر زمان‌بندی پاسخ اثر می‌گذارد. «Retry On Fail» یک گره را تا موفقیت دوباره اجرا می‌کند. اجرای ناموفق را می‌توان دوباره تلاش کرد و در دادهٔ خطا فیلد execution.retryOf فقط در این حالت هست. AWS Builders' Library یادآوری می‌کند که تکرار تنها برای APIهای ایدمپوتنت امن است و تکرار انبوه خود بار را تقویت می‌کند، پس backoff با jitter و سقف تلاش لازم است.

کلید ایدمپوتنسی

الگوی استاندارد را Stripe توضیح می‌دهد: کلاینت یک کلید یکتا (تا ۲۵۵ نویسه) می‌فرستد؛ سرور پاسخ نخستین درخواست را بعد از شروع اجرا ذخیره و برای همان کلید بازپخش می‌کند، حتی اگر پاسخ ۵۰۰ بوده باشد؛ اگر با همان کلید پارامتر دیگری بفرستید خطا می‌گیرید؛ ۴۰۹ یعنی درخواست هم‌کلید هنوز در جریان است؛ و کلیدها دست‌کم پس از ۲۴ ساعت ممکن است حذف شوند. Stripe پیشنهاد می‌کند کلید را از یک شیء مرتبط (مثل سبد خرید) بسازید. نتیجهٔ ۵۰۰ نامعین است: پیش از تکرار با کلید جدید باید وضعیت را تطبیق دهید.

در n8n، این یعنی:

• کلید را از دادهٔ پایدار بسازید (شناسهٔ رویداد فرستنده، شناسهٔ سفارش + نوع عمل)، نه از زمان یا عدد تصادفی که در هر تلاش عوض می‌شود.
• همان کلید را در هر تلاش (از جمله Retry On Fail) به API مقصد بدهید؛ اگر مقصد از ایدمپوتنسی پشتیبانی نمی‌کند، لایهٔ بعدی لازم است.
• کلید باید به درخواست یکسان گره بخورد؛ اگر پارامترها فرق کنند، رفتار مقصد را باید در مستندات خودش بخوانید.

دفتر پردازش: Remove Duplicates و Data Table

اگر مقصد ایدمپوتنسی ندارد، خودتان یک «دفتر پردازش» نگه دارید. n8n دو ابزار دارد.

گرهٔ Remove Duplicates با عملیات «Remove Items Processed in Previous Executions» و گزینهٔ «Value Is New» آیتم‌هایی را که شناسهٔ آن‌ها قبلاً دیده شده حذف می‌کند. دامنهٔ ذخیره «گره» (پیش‌فرض) یا «گردش‌کار» است و History Size پیش‌فرض ۱۰٬۰۰۰ آیتم است؛ یعنی شناسه‌های قدیمی‌تر از حافظه بیرون می‌روند و این برای رویدادهایی که ممکن است هفته‌ها بعد دوباره بیایند محدودیت است. عملیات «Clear Deduplication History» کل تاریخچه را پاک می‌کند، پس مراقب اجرای ناخواستهٔ آن باشید.

Data Table عملیات insert, update, upsert, delete و get دارد. upsert اگر ردیف مطابق شرط وجود داشته باشد آن را به‌روزرسانی و وگرنه ردیف می‌سازد؛ Dry Run هم دارد. می‌توانید جدولی با ستون‌های event_id، status و updated_at بسازید. نکتهٔ مهم (تحلیل نویسنده، نه ادعای مستندات): «بررسی سپس عمل» اتمی نیست؛ دو اجرای همزمان با یک شناسه ممکن است هر دو پیش از ثبت، «جدید» ببینند. برای همزمانی، مقصد باید خود ایدمپوتنت باشد یا درخواست‌ها پشت صف/کنترل همزمانی مرتب شوند. مستندات n8n تضمین اتمی‌بودن را در این صفحات ننوشته است.

حالت‌های پردازش

یک الگوی عملی (توصیهٔ نویسنده) سه حالت دارد:

1. received: رویداد دریافت شد و هنوز اثر جانبی رخ نداده.
2. done: اثر جانبی با موفقیت انجام شد و نتیجه (مثلاً شناسهٔ سفارش) ثبت شد.
3. unknown: درخواست به مقصد رفت ولی نتیجه معلوم نیست (تایم‌اوت یا ۵۰۰).

رفتار: رویدادی که done دارد دوباره اجرا نمی‌شود؛ unknown قبل از هر تکرار باید با پرس‌وجو از مقصد تطبیق شود (همان توصیهٔ Stripe دربارهٔ ۵۰۰)، و فقط پس از تطبیق با همان کلید تکرار شود.

تلاش مجدد کنترل‌شده

در تنظیمات گره، «Retry On Fail» و «On Error» را می‌توان تعیین کرد؛ On Error اجازه می‌دهد گردش‌کار متوقف شود، ادامه یابد یا با «خروجی خطا» مسیر جدا بگیرد. توصیه‌ها:

• Retry On Fail را فقط روی گره‌هایی روشن کنید که مقصد ایدمپوتنت است یا کلید می‌گیرد.
• برای خطاهای دائمی (۴xx اعتبارسنجی) تلاش مجدد بی‌فایده است؛ به «خروجی خطا» هدایت کنید.
• تعداد تلاش را محدود و فاصله را افزایشی کنید؛ AWS backoff با jitter و محدودکردن تلاش مجدد را برای جلوگیری از تقویت بار توصیه می‌کند.
• تنظیم «Execute Once» را برای گره‌های اثر جانبی با آیتم‌های چندگانه بسنجید تا برای هر آیتم ورودی تکرار نشود، مگر هدف همین باشد.

صف خطا (dead-letter)

n8n یک «dead-letter queue» آماده ندارد که در این مستندات توصیف شده باشد؛ آنچه هست گردش‌کار خطا با Error Trigger است. می‌توانید خودتان یک الگو بسازید: در گردش‌کار خطا، رویداد و پیام خطا را در یک جدول failed_events بنویسید و هشدار بفرستید؛ یک گردش‌کار دستی یا زمان‌بندی‌شده پس از بررسی انسانی همان رویداد را با همان کلید دوباره اجرا کند. داده‌ی خطا شامل execution.retryOf است فقط هنگام تلاش مجدد، و execution.id و execution.url نیازمند ذخیرهٔ اجرا هستند و اگر خطا در گرهٔ تریگر رخ دهد نیستند؛ بنابراین ذخیرهٔ اجراهای ناموفق را خاموش نکنید. پایش را با پایش سیستم کامل کنید.

مثال: وب‌هوک پرداخت

سناریوی ساختگی: درگاه فرضی رویداد evt_demo_1001 را به n8n می‌فرستد.

1. وب‌هوک با احراز هویت دریافت می‌کند و در یک جدول رویداد، upsert با وضعیت received انجام می‌دهد.
2. اگر وضعیت از قبل done است، به درگاه ۲۰۰ برمی‌گردد و چیزی اجرا نمی‌شود.
3. ایجاد سفارش با کلید order-demo-1001-create به API مقصد فرستاده می‌شود.
4. موفقیت: وضعیت done و شناسهٔ سفارش ثبت می‌شود.
5. تایم‌اوت یا ۵۰۰: وضعیت unknown؛ گردش‌کار خطا هشدار می‌دهد و تطبیق انجام می‌شود.
6. تلاش مجدد با همان کلید، یا تصمیم انسانی در صورت ناسازگاری.

این طراحی کپی‌شدن رویداد توسط فرستنده، Retry On Fail و تلاش مجدد دستی را یکسان مهار می‌کند. در شرایط همزمانی بالا باید آن را با آزمون بار بسنجید؛ ما چنین آزمونی نکرده‌ایم.

آزمون

• همان رویداد را دو بار پشت‌سرهم بفرستید و بررسی کنید فقط یک اثر جانبی ایجاد شده است.
• خطای ۵۰۰ مصنوعی در مقصد ایجاد کنید و مسیر unknown را ببینید.
• اجرای ناموفق را دستی تلاش مجدد کنید و ثبت دفتر را بررسی کنید.
• دو درخواست همزمان بفرستید و رفتار را مشاهده کنید.
• تاریخچهٔ Remove Duplicates را پاک و رفتار را بسنجید (آگاهانه، در محیط آزمایش).

اشتباهات رایج

• ساختن کلید از زمان یا uuid جدید در هر تلاش.
• روشن‌کردن Retry On Fail روی گره‌ای که مقصدش ایدمپوتنت نیست.
• اتکا به History Size پیش‌فرض برای رویدادهای دیرهنگام.
• پاسخ‌دادن به فرستندهٔ وب‌هوک بعد از کار طولانی و دریافت ارسال مجدد.
• تکرار ۵۰۰ بدون تطبیق.
• خاموش‌کردن ذخیرهٔ اجراهای ناموفق و از دست‌دادن داده خطا.

چک‌لیست

1. همهٔ منابع تکرار (وب‌هوک، Retry، دستی، همزمانی) فهرست شده‌اند.
2. کلید از دادهٔ پایدار ساخته می‌شود و در هر تلاش ثابت است.
3. مقصد کلید ایدمپوتنسی می‌گیرد یا دفتر پردازش داریم.
4. وضعیت‌های received، done و unknown تعریف و تطبیق مشخص است.
5. Retry On Fail فقط روی گره‌های امن و محدود روشن است.
6. گردش‌کار خطا و جدول رویدادهای ناموفق وجود دارد.
7. آزمون ارسال دوباره و ۵۰۰ مصنوعی انجام شده است.
8. برنامهٔ پاک‌سازی دفتر (پس از چند روز/هفته) مشخص است.

برای چارچوب کلی آمادگی تولید نرم‌افزار آمادهٔ تولید را هم ببینید.

منابع و مراجع

• Remove Duplicates node — n8n Docs، 2026-10-19.
• Data Table node: row operations — n8n Docs، 2026-10-19.
• Handle errors gracefully — n8n Docs، 2026-10-19.
• Work with nodes (node settings) — n8n Docs، 2026-10-19.
• Webhook node — n8n Docs، 2026-10-19.
• Idempotent requests — Stripe.
• Advanced error handling — Stripe.
• Timeouts, retries, and backoff with jitter — Amazon Builders' Library (Marc Brooker)، 2019-12-05.