خطای 429 را کورکورانه تکرار نکنید؛ SDK شاید خودش دوباره تلاش کند

طبق راهنمای محدودیت نرخ OpenAI، پاسخ 429 می‌تواند به محدودیت موقت یا سقف سخت هزینه مربوط باشد و ازدحام موقت مدل نیز ممکن است با 503 برگردد. بنابراین پیش از تکرار درخواست، وضعیت HTTP، کد خطا، متن پاسخ و سرآیند Retry-After را با هم بخوانید: برای محدودیت موقت صبر کنید، اما خطایی را که به اقدام در حساب یا پرداخت نیاز دارد به صف retry نفرستید.

پیش از ساختن حلقهٔ تلاش مجدد، رفتار SDK نصب‌شده را بررسی کنید؛ ممکن است هر فراخوانی برنامه را خودش چند بار ارسال کند. یک بودجه برای تعداد ارسال‌ها و مهلت کل عملیات تعیین کنید، سپس انتظار و صف را در همان بودجه جا دهید. کارگرهای هم‌زمان نیز باید از ظرفیت مشترک پیروی کنند تا پس از پایان انتظار، همگی در یک لحظه دوباره درخواست نفرستند.

از متن خطا بفهمید چه چیزی محدود شده است

کد وضعیت به‌تنهایی نمی‌گوید کدام ظرفیت پر شده است. پاسخ ممکن است محدودیت تعداد درخواست، حجم توکن یا سرعت افزایش ترافیک را مشخص کند. اگر محدودیت در یک بازهٔ زمانی بازنشانی می‌شود، کاهش آهنگ ارسال و انتظار معنا دارد؛ اگر اعتبار یا سقف هزینه تمام شده، گذشت چند ثانیه آن را برطرف نمی‌کند. کد اختصاصی ارائه‌دهنده و وضعیت حساب، مرز این دو مسیر را روشن‌تر می‌کند.

توضیح Claude دربارهٔ محدودیت‌های API درخواست در دقیقه، توکن ورودی در دقیقه و توکن خروجی در دقیقه را سنجه‌های جداگانه می‌داند؛ عبور از هرکدام پاسخ 429 با شرح محدودیت نقض‌شده و سرآیند retry-after برمی‌گرداند. پس کم بودن شمار درخواست‌ها به‌تنهایی نشانهٔ ظرفیت آزاد نیست. ورودی بزرگ یا خروجی طولانی می‌تواند پیش از رسیدن به سقف تعداد درخواست، ظرفیت توکن را مصرف کند.

ازدحام خود سرویس نیز مسیر تشخیص جداگانه‌ای دارد. در این وضعیت، انتظار و تلاش محدود ممکن است درخواست را به نتیجه برساند، اما کم‌کردن هم‌زمانی برنامه لزوماً بار سرویس را از بین نمی‌برد. برای تصمیم‌گیری، وضعیت HTTP را با کد و متن خطا ترکیب کنید؛ قانونی که همهٔ پاسخ‌های ناموفق را یکسان تکرار کند، خطاهای نیازمند اقدام را هم وارد صف انتظار می‌کند.

زمان انتظار را با مهلت کل عملیات هماهنگ کنید

اگر Retry-After معتبر دریافت کردید، آن را حداقل فاصله تا ارسال بعدی بدانید و کمی تأخیر تصادفی به آن بیفزایید. این فاصلهٔ اضافی باعث می‌شود کارگرهایی که با هم محدود شده‌اند، هم‌زمان بازنگردند. اگر زمان اعلام‌شده از مهلت باقی‌ماندهٔ کار بیشتر است، کار را برای موعد مناسب به صف بسپارید یا آن را با خطایی روشن پایان دهید؛ کوتاه‌کردن انتظار فقط برای جا شدن در مهلت، احتمال محدودشدن دوباره را بالا می‌برد.

در نبود سرآیند معتبر، تأخیر نمایی همراه با jitter جایگزین مناسبی است: پس از هر شکست، فاصلهٔ پایه را افزایش دهید، سقفی برای آن بگذارید و زمان دقیق ارسال را کمی تصادفی کنید. مقدار پایه و سقف به نیاز زمانی برنامه و ظرفیت ارائه‌دهنده بستگی دارند. فرمول تأخیر به‌تنهایی کافی نیست؛ شمار تلاش‌ها و مدت کل عملیات نیز باید پیش از نخستین ارسال محدود شده باشند.

مهلت کل را از زمان ورود کار حساب کنید، نه از لحظهٔ آخرین تماس شبکه. انتظار در صف، مکث میان تلاش‌ها، زمان پاسخ و ارسال‌های احتمالی SDK همگی از همین مهلت مصرف می‌کنند. زمان‌سنج یک درخواست شبکه ممکن است با هر تلاش تازه از نو آغاز شود؛ اگر تنها به آن تکیه کنید، کاری که پاسخ دیرهنگامش دیگر به درد نمی‌خورد همچنان در حال انتظار یا ارسال می‌ماند.

سرآیندهای ظرفیت باقی‌مانده و زمان بازنشانی، در صورت ارائه‌شدن، به زمان‌بندی پذیرش کار کمک می‌کنند. بااین‌حال، وقتی Retry-After صریح دارید، زمان بازنشانی یک سنجه را جای آن نگذارید؛ ممکن است چند محدودیت هم‌زمان برقرار باشند. در ثبت خطا، سنجهٔ محدودشده، انتظار اعلام‌شده و زمان واقعی ارسال بعدی را کنار هم نگه دارید تا روشن شود صف با ظرفیت هماهنگ است یا دوباره زودتر از موعد کار آزاد می‌کند.

تلاش‌های SDK را در بودجهٔ واقعی بشمارید

مستندات SDK پایتون OpenAI می‌گوید خطاهای واجد شرایط، از جمله 429، به‌طور پیش‌فرض تا دو بار دیگر تکرار می‌شوند و گزینهٔ max_retries این رفتار را تنظیم یا غیرفعال می‌کند. بنابراین یک فراخوانی از دید برنامه می‌تواند بیش از یک ارسال HTTP داشته باشد. رفتار نسخه و تنظیمات SDK نصب‌شده را مبنا بگذارید، زیرا همهٔ SDKها یک بودجه یا شیوهٔ یکسان برای انتظار ندارند.

در یک مثال فرضی، اگر حلقهٔ برنامه تا سه بار SDK را صدا بزند و هر فراخوانی شامل یک ارسال اولیه و دو تکرار داخلی باشد، یک کار می‌تواند تا ۹ ارسال HTTP ایجاد کند. این حاصل‌ضرب، سقف همان تنظیم فرضی است؛ موفقیت زودتر یا خطایی که واجد شرایط retry نیست، شمار واقعی را کمتر می‌کند. همین تفاوت میان «فراخوانی برنامه» و «ارسال شبکه» دلیل خطرناک بودن افزودن یک حلقهٔ عمومی بدون دیدن تنظیمات SDK است.

اگر برنامه باید Retry-After، صف و مهلت کل را خودش اداره کند، تکرار داخلی SDK را غیرفعال کنید. اگر آن را نگه می‌دارید، ارسال‌های احتمالی‌اش را در سقف تلاش و زمان عملیات حساب کنید و بررسی کنید با تأخیر طولانی اعلام‌شده از سوی سرور چه می‌کند. پس از شروع دریافت خروجی جریانی نیز درخواست را کورکورانه بازپخش نکنید؛ بخشی از خروجی ممکن است پیش‌تر به برنامه رسیده باشد.

صف را با نرخ پذیرش و هم‌زمانی مهار کنید

مکث یک کار، جلوی ورود کارهای تازه را نمی‌گیرد. اگر کارگرهای جدید همچنان با سرعت قبلی درخواست بفرستند، پایان هر دورهٔ انتظار موج دیگری از محدودیت می‌سازد. برای هر ظرفیتی که واقعاً میان کارگرها مشترک است، سقف درخواست‌های درحال‌اجرا و آهنگ شروع کار تعیین کنید. کنترل‌کننده باید میان همان کارگرها مشترک باشد؛ سقف مستقل در هر فرایند، ظرفیت مشترک ارائه‌دهنده را حفظ نمی‌کند.

پذیرش کار را با سنجه‌ای هماهنگ کنید که محدود شده است. برای محدودیت تعداد درخواست، نرخ شروع اهمیت دارد؛ برای محدودیت توکن، اندازهٔ ورودی و برآورد خروجی نیز مهم است. چون مصرف خروجی پیشاپیش قطعی نیست، برآورد را با مصرف واقعی اصلاح کنید. وقتی پاسخ خطا نشان می‌دهد توکن‌ها عامل محدودیت‌اند، تنها زیادکردن فاصلهٔ retry کافی نیست؛ اندازهٔ کار یا سرعت ورود کار تازه هم باید تغییر کند.

صف باید مهلت هر کار را بداند. کاری که پیش از رسیدن نوبتش مهلتش تمام می‌شود نباید صرفاً برای خالی‌کردن صف ارسال شود. اگر زمان انتظار صف از زمان قابل‌قبول برنامه عبور کرد، پذیرش کار جدید را کند کنید یا پاسخ قابل‌فهمی برای تلاش در زمان دیگر بدهید. نگه‌داشتن نامحدود کارها خطا را از دید کاربر پنهان می‌کند، اما ظرفیت بیشتری ایجاد نمی‌کند.

در اجرا، مسیر تصمیم چنین است: ابتدا نوع خطا را تشخیص دهید؛ خطای نیازمند اقدام را متوقف کنید؛ برای محدودیت موقت، انتظار معتبر سرور یا backoff همراه jitter را حساب کنید؛ آن را با مهلت و سقف تلاش بسنجید؛ سپس ارسال بعدی را از کنترل‌کنندهٔ مشترک ظرفیت عبور دهید. شمار ارسال‌های واقعی HTTP و زمان سپری‌شده در صف را ثبت کنید. این دو اندازه نشان می‌دهند آیا تکرار داخلی و بیرونی درخواست‌ها را چندبرابر کرده‌اند و آیا کارگرها با آهنگی فراتر از ظرفیت دوباره فعال می‌شوند.

بیشتر بخوانید:

• Notion یا Linear؛ تیم‌های کوچک شاید به هر دو نیاز داشته باشند
• کپی ویدئوی YouTube را آرشیو نکنید؛ Archive چیزی را حذف نمی‌کند
• Google ADK یا OpenAI Agents SDK؛ اکوسیستم ابری انتخاب را عوض می‌کند