Errors, Rate Limits and Retries
Classify errors, retry only retryable ones with exponential backoff and jitter, honour Retry-After, cap attempts, and use idempotency keys for POST.
بعد از این درس میتوانی
- خطاها را به شبکه و timeout، خطای کلاینت، محدودیت نرخ و خطای سرور دستهبندی کند و بگوید کدام قابل تکرار است.
- سیاست تلاش دوباره با فاصله افزایشی، تصادفیسازی، سقف تعداد و سقف زمان کل بنویسد و Retry-After را رعایت کند.
- خطر تلاش دوباره برای درخواستی که اثر دارد (POST) را توضیح بدهد و با کلید ایدمپوتنسی از اقدام تکراری جلوگیری کند.
- برای درخواستها timeout مناسب بگذارد و بداند timeout یعنی «نتیجه نامعلوم»، نه «انجام نشد».
چرا این درس مهم است
ورکفلوی ثبت تیکت برگ سبز یک تنظیم ساده داشت: «اگر خطا داد، ۵ بار دوباره امتحان کن». روزی سامانه تیکت کند شد؛ درخواستها پس از ۱۰ ثانیه timeout شدند و ورکفلو دوباره فرستاد. سامانه کند بود، نه خراب: همه درخواستها را ثبت کرد. نتیجه، برای بعضی پیامها پنج تیکت تکراری. همان روز کلید API مدل زبانی منقضی شد و ورکفلو هر پیام را پنج بار با خطای 401 فرستاد؛ لاگ پر شد و هیچکس خبردار نشد.
تلاش دوباره ابزار قدرتمندی است، به شرطی که بدانی کی، چند بار، با چه فاصلهای و برای چه نوع درخواستی. این درس همان طبقهبندی خطای درس آخر دوره پایه را در سطح HTTP و با کد واقعی میسازد.
مفاهیم کلیدی
یادآوری: خطای قابل تکرار، خطای غیرقابل تکرار و اجرای تکراری را در طرح خودکارسازی دوره پایه دیدی؛ کلاس کد وضعیت و ایدمپوتنت را در درس اول همین دوره.
- Rate Limit (محدودیت نرخ): سقف تعداد درخواست یا توکن در یک بازه زمانی که سرویس تعیین میکند؛ عبور از آن معمولاً 429 میدهد.
- Retry-After (هدر Retry-After): هدری که سرور در پاسخ میگذارد تا بگوید چقدر صبر کنی.
- Exponential Backoff (فاصله افزایشی): دو برابر کردن فاصله پس از هر تلاش ناموفق تا سرور فرصت بهبود داشته باشد.
- Jitter (تصادفیسازی فاصله): افزودن مقدار تصادفی به فاصله تا کلاینتهای زیاد همزمان دوباره هجوم نیاورند.
- Timeout (مهلت پاسخ): بیشینه زمانی که منتظر پاسخ میمانی؛ پس از آن درخواست را رها میکنی.
- Idempotency Key (کلید ایدمپوتنسی): شناسه یکتایی که با درخواست اثردار میفرستی تا سرور تکرار همان کار را تشخیص دهد و دوباره انجامش ندهد.
مدل ذهنی
تلاش دوباره را مثل زنگ زدن به یک دفتر شلوغ ببین. اگر بوق اشغال خورد (سرور موقتاً گرفتار)، کمی صبر میکنی و دوباره میگیری، هر بار کمی بیشتر؛ و اگر هزار نفر همزمان پشت خطاند، بهتر است همه دقیقاً سر یک ثانیه دوباره نگیرند. اگر پیغام گفت «این شماره وجود ندارد» (خطای کلاینت)، صد بار گرفتن عوضش نمیکند. و اگر وسط سفارش دادن تماس قطع شد، نمیدانی سفارش ثبت شد یا نه؛ پس دوباره که زنگ زدی، اول شماره پیگیری همان سفارش را میگویی.
تصمیم پس از هر پاسخ ناموفق
این تشبیه کجا غلط است؟ در تلفن، وقتی اشغال است میدانی کسی جواب نداده. در HTTP، timeout یعنی پاسخ را نگرفتی، نه اینکه سرور کاری نکرد. سرور ممکن است درخواست را کامل انجام داده باشد و فقط پاسخ دیر رسیده باشد. برای همین تلاش دوباره روی درخواست اثردار بدون کلید ایدمپوتنسی، کار را دو بار انجام میدهد.
گامبهگام
گام ۱: خطا را دستهبندی کن
| دسته | نمونه | قابل تکرار؟ |
|---|---|---|
| شبکه یا timeout | Connection refused، پاسخ نیامد | بله، با احتیاط برای درخواست اثردار |
| خطای کلاینت | 400، 401، 403، 404، 415 | خیر؛ درخواست یا دسترسی را درست کن |
| محدودیت نرخ | 429 | بله، پس از صبر |
| خطای سرور | 500، 502، 503، 504 | بله، چند بار محدود |
دو استثنای مهم در مستندات ارائهدهندگان: Claude API پاسخ 429 را هم برای عبور از محدودیت نرخ میدهد و هم برای رسیدن به سقف هزینه ماهانه؛ در حالت دوم هدر retry-after نیست و تا باز شدن دسترسی شکست ادامه دارد. همان مستندات برای خطای 500 تلاش دوباره با فاصله افزایشی را توصیه میکندsrc-claude-api-errors. یعنی حتی 429 را هم کورکورانه تکرار نکن: اگر Retry-After نیامد و تکرارها ادامه داشت، هشدار بده.
گام ۲: محدودیت نرخ و Retry-After
طبق MDN، 429 یعنی در یک بازه زمانی درخواست زیادی فرستادهای، و سرور ممکن است با هدر Retry-After بگوید چقدر صبر کنی؛ نحوه شمارش هم از سرویسی به سرویس دیگر فرق دارد (برای کل سرور یا هر منبع، بر اساس IP یا حساب)src-mdn-429. ارائهدهندگان مدل معمولاً هم تعداد درخواست و هم تعداد توکن را در دقیقه میشمارند؛ هر کدام زودتر پر شود، 429 میگیریsrc-openai-rate-limits.
نکتهای که خیلیها نمیدانند: در مستندات OpenAI آمده که درخواستهای ناموفق هم در سقف دقیقهای شمرده میشوند، پس فرستادن پشت سر هم کمکی نمیکندsrc-openai-rate-limits.
گام ۳: سیاست تلاش دوباره
راهنمای محدودیت نرخ OpenAI اینها را توصیه میکند: فاصله افزایشی همراه با مقدار تصادفی، Retry-After بهعنوان کمینه صبر، و سقف برای تعداد تلاش و زمان کلsrc-openai-rate-limits. SDK رسمی Claude هم خطاهای گذرا را بهطور پیشفرض دو بار با فاصله افزایشی و رعایت Retry-After تکرار میکندsrc-claude-api-errors. اگر از SDK استفاده میکنی، تلاش دوباره خودت را روی تلاش دوباره SDK سوار نکن؛ وگرنه تعداد واقعی تلاشها ضرب میشود.
یک سیاست ساده که در assets/retry_demo.py پیاده شده است:
| تنظیم | مقدار نمونه | چرا |
|---|---|---|
| کدهای قابل تکرار | 408، 429، 500، 502، 503، 504 و خطای شبکه | بقیه با تکرار درست نمیشوند |
| بیشینه تلاش | ۴ | بیشتر، فقط بار اضافه |
| فاصله | ۰٫۵، ۱، ۲، ۴ ثانیه (بیشینه ۸)، هرکدام تصادفی بین صفر و آن مقدار | فاصله افزایشی با تصادفیسازی |
| Retry-After | کمینه صبر + کمی تصادفی | حرف سرور مقدم است |
| زمان کل | ۳۰ ثانیه | ورکفلو بیپایان معطل نمیماند |
| پس از سقف | صف انسانی یا هشدار | هیچ خطایی بیصدا نیست |
گام ۴: timeout یعنی نتیجه نامعلوم
برای هر درخواست timeout بگذار؛ بدون آن، یک سرویس کند میتواند کل ورکفلو را معطل کند. ولی بدان: timeout یعنی نمیدانی چه شد. برای GET مهم نیست؛ دوباره بخوان. برای POST ممکن است سرور کار را انجام داده باشد. Claude API هم برای درخواستهای طولانی (بیش از ۱۰ دقیقه) استفاده از پاسخ جریانی یا پردازش دستهای را بهجای منتظر ماندن توصیه میکندsrc-claude-api-errors؛ timeout باید با نوع کار تناسب داشته باشد.
گام ۵: کلید ایدمپوتنسی برای درخواست اثردار
POST ایدمپوتنت نیستsrc-mdn-idempotent؛ هر تکرار ممکن است چیز تازهای بسازد. راه حل رایج: یک شناسه یکتا برای هر کار منطقی بساز (نه هر تلاش) و در هدر بفرست. سرویسی که از آن پشتیبانی کند، تکرار با همان کلید را تشخیص میدهد و نتیجه قبلی را برمیگرداند. API آزمایشی برگ سبز هدر Idempotency-Key را میپذیرد: بار دوم کد 200 و همان تیکت.
اگر سرویس مقصد کلید ایدمپوتنسی را نمیشناسد، دو راه داری: پیش از تکرار بخوان که کار انجام شده یا نه (مثلاً تیکتی با همان شناسه پیام هست؟)، یا تکرار نکن و به صف انسانی بفرست. نام این ویژگی در هدرها بین سرویسها یکسان نیست؛ مستندات هر سرویس را ببین.
مثالها
پیادهسازی عملی
آزمودن سیاست تلاش دوباره با API آزمایشی. حدود ۲۰ دقیقه. API آزمایشی چهار رفتار عمدی دارد: /flaky دو بار 503 و بار سوم 200؛ /limited بیش از سه درخواست در ده ثانیه 429 با Retry-After؛ /slow چند ثانیه دیر جواب میدهد؛ و /tickets کلید ایدمپوتنسی را میشناسد.
اجرای محلی
API آزمایشی (shared/barg-sabz-mock-api.py) را اجرا کن و در پنجره دیگر:
python retry_demo.py flaky
python retry_demo.py limited
python retry_demo.py slow
python retry_demo.py ticket
python retry_demo.py authبرای هر اجرا در یک جدول بنویس: چند تلاش، چرا تلاش دوباره شد یا نشد، و آخرش چه شد. بعد در assets/retry_demo.py کلید ایدمپوتنسی را برای هر تلاش تازه بساز (خط key = ... را داخل حلقه ببر) و ticket را دوباره اجرا کن؛ GET /tickets نشان میدهد چند تیکت ساخته شد.
بدون اجرا / شبیهساز
assets/sample-run.txt خروجی همین پنج اجرا را دارد. جدول را از روی آن پر کن و پاسخ بده: چرا اجرای auth فقط یک تلاش دارد؟ چرا در limited صبر بعد از 429 حدود ده ثانیه است و نه نیم ثانیه؟ چرا در ticket بار دوم کد 200 است؟
بدون کد
همین سیاست را برای یک گره HTTP Request در ابزار بدون کد بنویس (روی کاغذ یا در توضیح گره): کدام خطاها تکرار شوند، چند بار، فاصله، و مسیر پس از آخرین شکست. اگر ابزارت فقط «تعداد تلاش و فاصله ثابت» دارد، بنویس چه چیزی از سیاست کامل جا میماند و چطور با مسیر خطا جبرانش میکنی.
با کد
تابع backoff_delay در retry_demo.py را بخوان. آن را طوری تغییر بده که اگر Retry-After بیش از ۲۰ ثانیه بود، بهجای صبر، مستقیم «giving up» کند (بودجه زمان کل ۳۰ ثانیه است). با python retry_demo.py limited آزمایش کن.
اشتباههای رایج
| اشتباه | نتیجه | کار درست |
|---|---|---|
| تلاش دوباره برای همه خطاها | 401 هزاران بار تکرار میشود | فقط کدهای قابل تکرار |
| فاصله ثابت و بدون تصادفیسازی | همه کلاینتها همزمان دوباره هجوم میآورند | فاصله افزایشی + تصادفی |
| نادیدهگرفتن Retry-After | 429 ادامه دارد | Retry-After کمینه صبر است |
| بدون timeout | ورکفلو معطل یک سرویس کند میماند | timeout متناسب با کار |
| تکرار POST بدون کلید ایدمپوتنسی | تیکت یا پرداخت تکراری | کلید یکتا برای هر کار منطقی |
| ساختن کلید تازه در هر تلاش | کلید بیاثر میشود | یک کلید برای همه تلاشهای یک کار |
| تلاش دوباره خودت روی تلاش دوباره SDK | تلاشها ضرب میشوند | یکی را خاموش کن |
| شکست نهایی بیصدا | مشکل هفتهها دیده نمیشود | صف انسانی یا هشدار |
اشکالزدایی
دستهای از درخواستها پشت سر هم 429 میگیرند و تلاشهای دوباره هم.
ورکفلو درخواستها را همزمان یا پشت سر هم میفرستد و تلاشهای دوباره هم در سقف شمرده میشوند.
زمان درخواستها و هدرهای باقیمانده سقف (اگر سرویس میفرستد) را ببین.
همزمانی را کم کن، بین درخواستها فاصله بگذار، Retry-After را رعایت کن؛ اگر کار دستهای است، سرویس دستهای ارائهدهنده را بررسی کن.
پس از timeout و تلاش دوباره، دو رکورد یکسان ساخته شده است.
سرور تلاش اول را انجام داده بود و فقط پاسخ دیر رسید؛ تلاش دوم بدون کلید ایدمپوتنسی بود.
زمان ساخت دو رکورد را با زمان دو تلاش مقایسه کن.
کلید ایدمپوتنسی یکسان برای همه تلاشهای یک کار؛ اگر سرویس پشتیبانی نمیکند، پیش از تکرار وجود رکورد را بررسی کن.
لاگ پر از 401 تکراری است و ساعتها کسی خبردار نشده.
سیاست تلاش دوباره خطای غیرقابل تکرار را هم تکرار میکند و پس از سقف بیصدا تمام میشود.
در لاگ ببین آیا برای 401 بیش از یک تلاش ثبت شده است.
401 و 403 را از فهرست قابل تکرار خارج کن؛ برایشان توقف و هشدار فوری بگذار.
نکتههای هزینه
تمرین کوتاه
تمرین · 10 دقیقه
هدف: تصمیم درست برای هر پاسخ.
گامها: برای هر مورد بنویس: تکرار بشود یا نه، چند بار و با چه صبری، و پس از شکست نهایی چه شود.
- GET وضعیت سفارش: 503.
- POST ثبت تیکت: timeout پس از ۱۰ ثانیه، بدون پاسخ.
- فراخوانی API مدل: 429 با
Retry-After: 20. - POST ثبت تیکت: 400
validation_error. - فراخوانی API مدل: 429 بدون Retry-After، سه بار پشت سر هم با فاصله افزایشی.
معیار پذیرش: ۱ و ۳ تکرار با صبر مناسب؛ ۲ تکرار فقط با همان کلید ایدمپوتنسی یا بررسی وجود؛ ۴ بدون تکرار؛ ۵ توقف و هشدار (احتمال سقف هزینه یا مشکل پایدار).
راهحل نمونه
۱: تکرار تا ۳–۴ بار با فاصله افزایشی تصادفی؛ بعد صف انسانی. ۲: نتیجه نامعلوم است؛ تکرار با همان کلید ایدمپوتنسی، یا اگر سرویس پشتیبانی نمیکند، اول بررسی وجود تیکت. ۳: دستکم ۲۰ ثانیه صبر بهعلاوه کمی تصادفی، اگر در بودجه زمان میگنجد؛ وگرنه صف یا زمانبندی بعدی. ۴: تکرار نکن؛ فیلد را درست کن یا به مسیر خطا بفرست. ۵: الگوی پایدار است، نه گذرا؛ توقف و هشدار به مسئول (مثلاً سقف هزینه پر شده).
چالش
تمرین · 30 دقیقه
موقعیت: کارتهای درخواست HTTP که در چالش درس اول برای کار خودت نوشتی، حالا سیاست خطا لازم دارند. اگر سرویس واقعی را نمیشناسی یا دادهاش حساس است، یک سرویس ساختگی با رفتار مشابه فرض کن.
- برای هر درخواست: کدهای قابل تکرار، بیشینه تلاش، فاصله، timeout و بودجه زمان کل.
- برای هر درخواست اثردار: کلید ایدمپوتنسی از کجا ساخته میشود (کدام شناسه منطقی) و اگر سرویس آن را نمیشناسد، جایگزینت چیست.
- برای هر شکست نهایی: صف انسانی یا هشدار، و به چه کسی.
- یک سناریوی «روز بد» بنویس (سرویس کند + محدودیت نرخ همزمان) و نشان بده سیاستت چه میکند.
خروجی مورد انتظار: جدول سیاست برای هر درخواست، روش جلوگیری از تکرار، مسیر شکست نهایی و تحلیل روز بد.
معیار پذیرش:
- 401 و 403 و 400 تکرار نمیشوند.
- فاصله افزایشی با تصادفیسازی است و Retry-After رعایت میشود.
- هر درخواست اثردار راه جلوگیری از تکرار دارد.
- هیچ شکست نهایی بیصدا نیست؛ دادههای نمونه ساختگی یا ناشناساند.
پرسشهای سنجش
جمعبندی
- خطاها چهار دستهاند: شبکه و timeout، کلاینت، محدودیت نرخ، سرور؛ خطای کلاینت (بهجز 408 و 429) تکرار نمیشود.
- تلاش دوباره: فاصله افزایشی با تصادفیسازی، Retry-After بهعنوان کمینه، سقف تعداد و سقف زمان کل.
- درخواست ناموفق هم در سقف نرخ شمرده میشود؛ هجوم دوباره کمکی نمیکند.
- timeout یعنی نتیجه نامعلوم؛ برای POST، تکرار فقط با کلید ایدمپوتنسی یکسان یا بررسی وجود.
- تلاش دوباره خودت را روی تلاش دوباره SDK سوار نکن.
- پس از آخرین شکست: صف انسانی یا هشدار، هرگز سکوت.
پرسشهای سنجش
ورکفلو این پاسخها را گرفته است: 404 برای یک سفارش، 502 از سرویس پیامک، Connection refused از API داخلی، 403 از صفحهگسترده، 429 از API مدل. هرکدام را دستهبندی کن و بگو قابل تکرار است یا نه.
پاسخ نمونه و معیار ارزیابی
404: خطای کلاینت، تکرار نه (شناسه یا مسیر را بررسی کن). 502: خطای سرور، تکرار محدود. Connection refused: خطای شبکه، تکرار محدود (و بررسی اینکه سرویس بالا هست). 403: خطای کلاینت (اختیار)، تکرار نه؛ توقف و هشدار. 429: محدودیت نرخ، تکرار پس از صبر با رعایت Retry-After.
- 404 و 403 را غیرقابل تکرار میداند (1 امتیاز)
- 502 و خطای شبکه را قابل تکرار محدود میداند (1 امتیاز)
- 429 را با صبر و Retry-After میداند (1 امتیاز)
- 403 را تکرار کن ← اختیار کلید با تکرار بیشتر نمیشود.
یک سیاست تلاش دوباره برای فراخوانی API مدل زبانی در ورکفلوی طبقهبندی پیام بنویس: کدهای قابل تکرار، بیشینه تلاش، فاصلهها، رفتار با Retry-After، بودجه زمان کل و رفتار پس از شکست نهایی.
پاسخ نمونه و معیار ارزیابی
قابل تکرار: 408، 429، 500، 502، 503، 504 (و اگر ارائهدهنده کد ویژهای برای شلوغی دارد، مثل 529 در Claude API) و خطای شبکه. بیشینه ۳ تا ۴ تلاش. فاصله افزایشی (مثلاً ۱، ۲، ۴ ثانیه) هرکدام تصادفی. Retry-After کمینه صبر است. بودجه کل مثلاً ۳۰ تا ۶۰ ثانیه. پس از شکست نهایی: پیام به صف انسانی با برچسب «طبقهبندی نشد» و هشدار اگر نرخ شکست بالا رفت. اگر از SDK استفاده میشود، تلاش دوباره SDK را حساب کن یا خاموش کن.
- فقط کدهای قابل تکرار (1 امتیاز)
- فاصله افزایشی تصادفی و Retry-After (1 امتیاز)
- سقف تعداد و زمان (1 امتیاز)
- مسیر پس از شکست نهایی (1 امتیاز)
- ۱۰ بار با فاصله ۱ ثانیه ← فاصله ثابت و زیاد بودن تلاشها فقط بار و هزینه اضافه میسازد.
پس از اضافهکردن تلاش دوباره به گره «ثبت سفارش سازمانی»، چند سفارش تکراری ثبت شده است. لاگ را بخوان و علت و اصلاح را بنویس.
لاگ ساختگی.
11:00:00 POST /bulk-orders key=a91f -> timeout after 10s 11:00:11 POST /bulk-orders key=c27e -> 201 id=BO-0418 (later) GET /bulk-orders?org=ORG-12 -> BO-0417 (11:00:06), BO-0418 (11:00:11)
پاسخ نمونه و معیار ارزیابی
تلاش اول timeout شد ولی سرور سفارش BO-0417 را ساخته بود. تلاش دوم با کلید ایدمپوتنسی تازه (c27e بهجای a91f) فرستاده شد، پس سرور آن را کار تازه دانست. اصلاح: کلید را یک بار برای هر کار منطقی بساز (مثلاً از شناسه ایمیل درخواست) و در همه تلاشها همان را بفرست؛ اگر سرویس کلید را نمیشناسد، پیش از تکرار وجود سفارش را بررسی کن.
- timeout را نتیجه نامعلوم میداند (1 امتیاز)
- کلید متفاوت در دو تلاش را علت میبیند (1 امتیاز)
- کلید ثابت برای کار منطقی یا بررسی وجود (1 امتیاز)
- timeout را بیشتر کن ← کمک میکند ولی ریشه را حل نمیکند؛ هر timeoutی ممکن است دوباره پیش بیاید.
سرور 429 با `Retry-After: 15` برگردانده است. سیاست تو فاصله افزایشی ۱، ۲، ۴ ثانیه دارد. تلاش بعدی کی باشد؟
- پس از ۱ ثانیه، طبق سیاست خودمان.
- دستکم پس از ۱۵ ثانیه، با کمی مقدار تصادفی اضافه.
- فوراً، چون 429 خطای موقت است.
- هرگز؛ 429 خطای کلاینت است.
پاسخ نمونه و معیار ارزیابی
- a ← زودتر از Retry-After، تقریباً حتماً دوباره 429 میگیری و در سقف هم شمرده میشود.
- c ← تلاش فوری همان چیزی است که محدودیت نرخ برای جلوگیریاش ساخته شده است.
- d ← 429 در دسته 4xx است ولی پس از صبر قابل تکرار است.
همکارت timeout همه گرههای HTTP را برداشته تا «هیچ درخواستی وسط کار قطع نشود». دو خطر این تصمیم را بگو و پیشنهاد بده.
پاسخ نمونه و معیار ارزیابی
خطر ۱: اگر سرویسی گیر کند، ورکفلو بیپایان معطل میماند و اجراهای بعدی پشتش جمع میشوند. خطر ۲: خطا دیده نمیشود؛ نه شکستی ثبت میشود نه هشداری. پیشنهاد: timeout متناسب با کار (مثلاً چند ثانیه برای خواندن، بیشتر برای کار سنگین)، و برای کارهای خیلی طولانی سازوکار جداگانه (پاسخ جریانی، کار دستهای یا پرسیدن وضعیت)؛ و برای درخواست اثردار، کلید ایدمپوتنسی تا تکرار پس از timeout امن باشد.
- معطلماندن ورکفلو (1 امتیاز)
- پنهانماندن خطا (1 امتیاز)
- timeout متناسب و راه جداگانه برای کار طولانی (1 امتیاز)
- مشکلی ندارد ← یک سرویس کند بدون timeout، همه ورکفلو را قفل میکند.
فایلهای درس
API آزمایشی با نقطههای پایانی ناپایدار، محدود و کند
barg-sabz-mock-api.pyنمونه سیاست تلاش دوباره با فاصله افزایشی و کلید ایدمپوتنسی
retry_demo.pyخروجی نمونه اجرای اسکریپت برای مسیر بدون اجرا
sample-run.txtابزارها و جایگزینها
- ویرایشگر متن — نوشتن سیاست خطا
منابع
Claude API errors Anthropic accessed 2026-10-16
429 Too Many Requests MDN Web Docs (Mozilla) living doc, accessed 2026-10-16; spec RFC 6585 §4
Rate limits OpenAI accessed 2026-10-16
Idempotent (Glossary) MDN Web Docs (Mozilla) living doc, accessed 2026-10-16