ظهور 429 في OpenAI API: هل ينبغي إعادة المحاولة باستمرار؟ 3 أنواع من الأسباب و5 مبادئ للمعالجة

ظهور 429 في OpenAI API: هل ينبغي إعادة المحاولة باستمرار؟ 3 أنواع من الأسباب و5 مبادئ للمعالجة

لا تُعِد المحاولة بلا توقف. عندما يعيد OpenAI API الرمز 429، فهذا لا يعني أن «الانتظار قليلًا سيجعل الأمور تتحسن». لا يصلح الانتظار ثم إعادة المحاولة إلا مع حدود المعدل المؤقتة. أما نفاد الحصة أو خلل الفوترة أو قيود الاستخدام على مستوى المؤسسة، فلا تتعافى مهما أعدت المحاولة، بل إن كثرة المحاولات قد تسد قائمة الانتظار.

الطريقة الصحيحة هي أن تبدأ بفحص رسالة الخطأ وerror.type وerror.code إن كان متاحًا، لتحدد أي نوع من 429 تواجهه. إذا كان السبب حدًّا مؤقتًا للمعدل، فإن وُجدت قيمة Retry-After صالحة فانتظر وفقها، وإلا فاستخدم تراجعًا أسيًا مع تذبذب عشوائي، مع تعيين حد أقصى لعدد المحاولات.

ماذا ستتعلم بعد قراءة هذا المقال؟

  • ما الفئات التي ينقسم إليها 429 من OpenAI API على الأقل، وكيف تتعامل مع كل فئة.
  • ما العلاقة بين Retry-After والتراجع الأسي والتذبذب العشوائي، ومتى تستخدم أيًا منها.
  • لماذا تتفاقم استجابات 429 عندما تتراكم إعادة المحاولة التلقائية في SDK الرسمي، وقائمة المهام، وزر «إعادة المحاولة» اليدوي.
  • الحلول المختلفة لاختناق عدد الطلبات مقابل اختناق الرموز (tokens)، وما يجب الانتباه إليه عند حدوث خطأ في منتصف طلب متدفق.

الفهرس: قبل الدخول في صلب المقال، نعرض جدولًا للمفاهيم ونظرة سريعة على التأثير، لمساعدتك على توحيد المصطلحات والعثور على الجزء الذي يخصك. يرتب قسم «حقائق موضوعية» ما تقوله الوثائق الرسمية لـ OpenAI عن 429، بما في ذلك تصنيف الأخطاء وقواعد إعادة المحاولة وسلوك SDK. أما قسم «التحليل والحكم» فيناقش التنفيذ الهندسي، بما في ذلك تعديل الاستراتيجية بحسب نوع عنق الزجاجة، وتصميم حالات قائمة الانتظار، وتشخيص تراكم إعادة المحاولة، والفروق الدلالية التي يجب الانتباه إليها عند الانتقال إلى بوابة أخرى.

openai-api-429-should-you-keep-retrying-ar-image-0


Table of Contents

للعلم: مفاهيم تحتاجها لفهم خطأ 429 في OpenAI API

المفهوم شرح موجز
HTTP 429 حالة “Too Many Requests” (طلبات كثيرة جدًا). يستخدمها OpenAI API للإشارة إلى حدود المعدل، وكذلك للإشارة إلى حدود الحصة أو الاستخدام
حد المعدل (Rate Limit) الحد الأعلى لعدد الطلبات التي يمكن إرسالها خلال فترة زمنية معينة. تحسب OpenAI عدد الطلبات وحجم tokens كلًا على حدة
RPM / TPM عدد الطلبات في الدقيقة، وعدد tokens في الدقيقة. بلوغ أيٍّ منهما الحد قد يؤدي إلى خطأ 429
error.type / error.code حقول منظمة داخل جسم استجابة الخطأ، تُستخدم لتمييز السبب الدقيق لخطأ 429، وهي أكثر موثوقية من الاعتماد على رمز الحالة وحده
Retry-After حقل في رأس الاستجابة يوضح المدة التي يقترح الخادم الانتظار قبل المحاولة مجددًا. وعندما تكون قيمته صالحة، يُفضّل الالتزام بها
التراجع الأُسّي (Exponential Backoff) بعد كل فشل، يزداد وقت الانتظار بمضاعفات، مثل ثانية واحدة، ثم ثانيتين، ثم 4 ثوانٍ، مع وضع حد أقصى
الاهتزاز العشوائي (Jitter) إضافة مقدار عشوائي إلى وقت التراجع، لتجنب قيام عدد كبير من العملاء بإعادة المحاولة في اللحظة نفسها
الإخراج المتدفق (Streaming) يعيد النموذج المحتوى أثناء توليده. وبمجرد بدء الإخراج، لا يمكن إعادة تشغيل الطلب بالكامل ببساطة إذا حدث خطأ في المنتصف
تراكم إعادة المحاولة قيام SDK وقائمة انتظار الأعمال وإجراءات المستخدم اليدوية بإعادة المحاولة كلٌّ على حدة، ما يضاعف حجم الطلبات الفعلي

نظرة سريعة على التأثير: ماذا يعني خطأ 429 في OpenAI API لكل دور

الدور التأثير الرئيسي النقاط التي يجب الانتباه إليها
مطورو الواجهة الخلفية كتابة منطق إعادة المحاولة بشكل خاطئ تحوّل تحديد المعدل المؤقت إلى عطل مستمر تمييز أنواع 429، وتوحيد إعادة المحاولة في طبقة واحدة
مسؤولو المعالجة الدفعية ومهام البيانات المهام ذات الأحجام الكبيرة قد تصطدم في الوقت نفسه بحدّي عدد الطلبات والـ tokens إيقاع الإرسال، وحجم السياق، وتصميم حالة قائمة الانتظار
المنتج والواجهة الأمامية تكرار المستخدم للنقر على “إعادة المحاولة” يولّد المزيد من أخطاء 429 إبلاغ المستخدم بوقت المحاولة التالية، أو توضيح أن السبب يتعلق بالحساب
العمليات وإدارة الحسابات أخطاء 429 المتعلقة بالحصة والفوترة لا يمكن حلها بالكود وحده اكتشاف حالة الحساب ومعالجتها في الوقت المناسب بدل ترك إعادة المحاولة التلقائية تعمل بلا رقيب

حقائق موضوعية: كيف تصف وثائق OpenAI الرسمية خطأ 429

يعتمد هذا الجزء على دليل رموز الأخطاء ودليل حدود المعدل ومقالة تشخيص 429 في مركز المساعدة، وكلها وثائق تحتفظ OpenAI بنشرها علنًا، وقد تم التحقق منها بتاريخ 2026-11-17. هذه وثائق صيانة تُحدَّث باستمرار، ولا يمكن لهذا المقال التأكد من تاريخ النشر الأول للمحتوى ذي الصلة، لذلك لا نتعامل معه كخبر اليوم، بل كبيان بالقواعد السارية حاليًا.

مصادر مختلفة لأخطاء 429 في OpenAI API

الموقف الأساسي في الوثائق الرسمية هو: رمز 429 نفسه قد يحمل معانٍ مختلفة، لذا يجب الحكم بناءً على رسالة الخطأ وerror.type وerror.code عند توفره. فمعالجة حدود المعدل المؤقتة تختلف عن معالجة الحصة أو الفوترة أو قيود استخدام المؤسسة.

النوع الأول يعني «الطلبات في النافذة الحالية أسرع أو أكثر من اللازم»، ويتعافى عادةً بمجرد تحديث النافذة بعد فترة. أما النوع الثاني فيتعلق بحالة الحساب نفسه، مثل نفاد الحصة أو مشكلة في الدفع أو حد استخدام على مستوى المؤسسة. وهذه المشكلات لا تزول تلقائيًا مع مرور الوقت.

نوع 429 الإشارات النمطية هل يحل الانتظار المشكلة الإجراء الموصى به
حد سرعة عدد الطلبات تشير رسالة الخطأ إلى الحد الأقصى لعدد الطلبات، ويكون code الشائع هو rate_limit_exceeded عادةً نعم اتبع Retry-After، أو استخدم تراجعًا أُسّيًا مع ارتجاف (jitter)
حد كمية token تشير رسالة الخطأ إلى الحد الأقصى لـ token عادةً نعم، لكنه يُستثار بسهولة بشكل متكرر قلّل كمية token في الطلب الواحد أثناء التراجع
قيود الحصة/الفوترة/المؤسسة تشير رسالة الخطأ إلى الحصة أو الفوترة، ويكون code الشائع هو insufficient_quota لا أوقف إعادة المحاولة التلقائية، وأبلغ المسؤول لمعالجة الحساب

يجدر التأكيد على أن القيم الفعلية لـerror.code يجب أن تُستناد إلى الاستجابة الفعلية والوثائق الرسمية. فالأكواد الواردة في الجدول أعلاه مجرد أمثلة شائعة، لذا لا تعتمد في الشفرة على سلاسل نصية مكتوبة يدويًا وحدها للحكم، واحتفظ برسالة الخطأ الأصلية لفحص السجلات.

حد عدد الطلبات وحد حجم الـ tokens قد يكونان منفصلين

يوضح دليل حدود المعدل أن الحدود تُقاس على أكثر من بُعد، وأكثر ما تصادفه هو عدد الطلبات وحجم الـ tokens، وكل منهما يسري بشكل مستقل. أي أنه حتى لو لم تكن قد اقتربت من سقف عدد الطلبات، فقد ترتطم أولاً بحد الـ tokens لأن كل طلب يحمل سياقًا طويلاً. والعكس صحيح أيضًا: عدد كبير من الطلبات الصغيرة جدًا قد يستهلك حد عدد الطلبات أولاً.

تقدّم OpenAI في ترويسات الاستجابة معلومات مرتبطة بحدود المعدل، مثل عدد الطلبات المتبقية وعدد الـ tokens المتبقية ووقت إعادة الضبط لكل منهما. تساعد هذه الترويسات في معرفة أيّ الحدّين أصبح أقرب قبل أن يصلك خطأ 429 فعليًا.

openai-api-429-should-you-keep-retrying-ar-image-1

الطرق التي توصي بها OpenAI رسميًا لإعادة المحاولة عند استجابة OpenAI API 429

بالنسبة لحالات تحديد المعدل المؤقتة التي يمكن حلها بإعادة المحاولة، يمكن تلخيص التوصيات الرسمية في نقطتين:

  1. إذا وُجدت قيمة صالحة لـ Retry-After، فاتبعها. فهي الإشارة الأكثر مباشرة من الخادم، وأدق من تقدير العميل بنفسه.
  2. إذا لم توجد Retry-After، فاستخدم التراجع الأسي المصحوب باهتزاز عشوائي. يزداد زمن الانتظار مع عدد مرات الفشل، ثم تُضاف إليه قيمة عشوائية، حتى لا تعيد جميع العملاء المحاولة في اللحظة نفسها.

تفترض هاتان القاعدتان أن «استجابة 429 هذه من النوع الذي يمكن حلّه بالانتظار». أما إذا كانت المشكلة متعلقة بالحصة أو الفوترة، فإن أدق خوارزمية تراجع لن تكون سوى دوران في الفراغ.

سلوك إعادة المحاولة التلقائية في SDK الرسمي

يعيد SDK الرسمي من OpenAI المحاولة تلقائيًا عند أخطاء تحديد المعدل المؤهلة، ويتأثر السلوك الفعلي بإعدادات العميل. في SDK بايثون مثلًا، يمكن ضبط ذلك عبر المعامل max_retries، أو تعيينه إلى 0 لتعطيل إعادة المحاولة التلقائية.

وهذا يعني أنه حتى لو لم تكتب سطرًا واحدًا من منطق إعادة المحاولة في كود العمل، فقد يكون الطلب قد أُعيدت محاولته عدة مرات. وإذا أضفت طبقة أخرى من إعادة المحاولة في طبقة الأعمال، فسيكون عدد الطلبات الفعلي حاصل ضرب الاثنين.

لا يمكن إعادة تشغيل الطلبات المتدفقة بالكامل عند حدوث خطأ في منتصفها

تشير الوثائق الرسمية أيضًا إلى حالة حدّية يسهل إغفالها: بمجرد أن يبدأ الإخراج المتدفق، فإن الأخطاء التي تحدث بعد ذلك لا يمكن معالجتها جميعًا بإعادة تشغيل الطلب كاملًا. فقد يكون المستخدم قد رأى جزءًا من المحتوى بالفعل، وقد تكون الأنظمة المتلقية قد استهلكت جزءًا من البيانات. وإعادة التشغيل المباشرة تؤدي إلى تكرار المحتوى وعدم اتساقه، كما تستهلك الرموز (tokens) مرة أخرى.


تحليل وحكم: كيف نطبّق OpenAI API 429 عمليًا في الهندسة

المحتوى التالي حكم هندسي مبني على الحقائق المذكورة أعلاه، وليس نصًا حرفيًا من OpenAI الرسمي.

مثال على التراجع الأسي لـ OpenAI API 429 قابل للتعديل مباشرة

يوضح المثال التالي عدة مبادئ: تعطيل إعادة المحاولة التلقائية في SDK بحيث تتولى طبقة الأعمال المسؤولية كاملة؛ ورمي أخطاء الحصة مباشرة؛ وتفضيل اتباع Retry-After؛ وعند عدم توفره، استخدام تراجع أسي مع تشويش كامل؛ وتحديد الحد الأقصى لعدد المحاولات.

import random
import time
from openai import OpenAI, RateLimitError

# تعطيل إعادة المحاولة التلقائية في SDK لتجنب التداخل مع إعادة المحاولة المخصصة أدناه
client = OpenAI(max_retries=0)

# أنواع 429 التي لا يمكن حلها بالانتظار (وفق الاستجابة الفعلية والوثائق الرسمية)
NON_RETRYABLE_CODES = {"insufficient_quota"}


def parse_retry_after(response):
    """تحليل عدد الثواني في Retry-After؛ وإرجاع None إذا كان غير صالح. يمكن إضافة تحليل تنسيق تاريخ HTTP عند الحاجة."""
    if response is None:
        return None
    value = response.headers.get("retry-after")
    try:
        seconds = float(value)
        return seconds if seconds >= 0 else None
    except (TypeError, ValueError):
        return None


def call_with_backoff(messages, model, max_attempts=5, base=1.0, cap=60.0):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except RateLimitError as e:
            if e.code in NON_RETRYABLE_CODES:
                raise  # مشكلات الحصة/الفوترة، تُترك لمسار معالجة الحساب
            if attempt == max_attempts - 1:
                raise  # تجاوز الحد الأقصى، يُترك لقائمة الانتظار أو التنبيه
            wait = parse_retry_after(e.response)
            if wait is None:
                # تشويش كامل: اختيار قيمة عشوائية ضمن [0, الحد الأسي الأعلى]
                wait = random.uniform(0, min(cap, base * 2 ** attempt))
            time.sleep(wait)

إن max_attempts وbase وcap في المثال مجرد نقطة بداية، وليست قيمًا موصى بها. تختلف حدود الحسابات باختلاف مستوى الحصة، وتختلف طبيعة المهام أيضًا، لذا لا يوجد عدد توافق موحّد أو عدد إعادات محاولة واحد يناسب جميع الحسابات، بل ينبغي ضبطها بناءً على بيانات المراقبة الخاصة بك.

الضبط حسب نوع عنق الزاوية: حلّ مشكلة عدد الطلبات يختلف عن حلّ مشكلة الرموز

التراجع (backoff) يعالج فقط سؤال «كيف أنتظر هذه المرة؟»، لكنه لا يجيب عن سؤال «لماذا أصطدم بالحد في كل مرة؟». لتقليل أخطاء 429، عليك أولًا أن تعرف أي حدّ بالضبط تصطدم به.

عنق عدد الطلبات مفتاحه هو تنظيم إيقاع الإرسال. طبّق تمريرًا بمعدّل ثابت عند مدخل قائمة الانتظار، مثل حزمة رموز (token bucket) أو إصدار بت intervals زمنية ثابتة، ولا تسمح لكمية كبيرة من المهام بالانطلاق في الثانية نفسها. وعند تشغيل المهام الدفعية، وزّع أوقات البدء بدلًا من إطلاقها كلها في اللحظة نفسها.

عنق الرموز مفتاحه هو تقليل حجم الطلب الواحد. من أشكال الهدر الشائعة: إرفاق موجه النظام الطويل وسجل المحادثة كاملًا في كل جولة؛ وإعادة إرسال المستند الكبير نفسه في طلبات متعددة؛ ودفع المادة كاملة إلى النموذج في حين أنك تحتاج جزءًا واحدًا منها فقط. إن قمت أولًا بالقص أو التلخيص أو الاسترجاع ثم أرسلت الطلب، فغالبًا ستحصل على نتيجة أفضل بكثير من مجرد زيادة عدد المحاولات.

openai-api-429-should-you-keep-retrying-ar-image-2

يجب أن تميز حالة قائمة الانتظار بين “انتظار إعادة المحاولة” و”حظر الحساب”

كثير من الأنظمة لا تمتلك سوى حالتين فقط: “في قائمة الانتظار” و”فشل”. وعند مواجهة الاستجابة 429، يتسبب هذا في نوعين من التقييم الخاطئ: الحد المؤقت لمعدل الطلبات يُعامل على أنه فشل فتُهمَل المهمة، ومشكلة الحصة يُعامل على أنها انتظار في الطابور فيحدث انتظار لا نهائي.

الطريقة الأكثر منطقية هي تقسيم نوعي 429 إلى حالتين، مع عرض مختلف لكل منهما:

حالة قائمة الانتظار شرط التفعيل المعلومات التي يجب عرضها المعالجة اللاحقة
انتظار إعادة المحاولة حد مؤقت لمعدل الطلبات الوقت المتوقع للمحاولة التالية، وعدد المحاولات التي تمت إعادة المحاولة تلقائيًا في الوقت المحدد، والتحول إلى فشل عند بلوغ الحد الأقصى
حظر الحساب الحصة، والفوترة، وحدود استخدام المؤسسة سبب الحظر (مثل عدم كفاية الحصة) إيقاف المهام اللاحقة للحساب نفسه مؤقتًا، وإشعار المسؤول
فشل تجاوز حد إعادة المحاولة أو خطأ آخر غير قابل للاسترداد نوع الخطأ والمعلومات الأصلية تدخل يدوي أو تخفيض مستوى الخدمة

ولـ”حظر الحساب” تأثير تابع. فالمهام الأخرى ضمن الحساب نفسه من المرجح أن تصطدم بالاستجابة 429 ذاتها، وفي هذه الحالة ينبغي الإيقاف الكلي بدلًا من ترك كل مهمة تصطدم بها بمفردها مرة واحدة.

تشخيص تراكم إعادة المحاولات: SDK وقائمة الانتظار وزر التشغيل اليدوي

إذا لاحظت أن أخطاء 429 تزداد سوءًا كلما أعدت المحاولة، فأول شيء يجب التحقق منه هو ما إذا كانت هناك طبقات متعددة من إعادة المحاولة تعمل في الوقت نفسه. المسار النموذجي هو: يعيد SDK المحاولة تلقائيًا عدة مرات، ثم تعيد قائمة انتظار الأعمال إرسال المهمة عدة مرات أخرى بعد فشلها، ثم يرى المستخدم في الواجهة الأمامية رسالة الخطأ فيضغط يدويًا على «إعادة المحاولة». بعد تضاعف هذه الطبقات الثلاث، قد يتحول طلب واحد أصلي إلى أكثر من عشرة طلبات فعلية، وغالبًا ما تتركز هذه الطلبات داخل نافذة تحديد المعدل، ما يزيد من حدة التقييد.

عند التشخيص، يُنصح بالتحقق من كل طبقة على حدة:

  • طبقة SDK: تحقق من القيمة الفعلية لـ max_retries، ولا تعتمد على القيمة الافتراضية التي تتذكرها.
  • طبقة قائمة الانتظار: تحقق مما إذا كانت المهمة تُعاد إرسالها تلقائيًا بعد الفشل، وما إذا كانت إعادة الإرسال تتضمن تراجعًا زمنيًا (backoff).
  • طبقة التفاعل: تحقق مما إذا كان زر «إعادة المحاولة» معطلاً أثناء فترة الانتظار، وهل يعرض وقت المحاولة التالية.
  • طبقة السجلات: خصّص معرّفًا فريدًا لكل مهمة أصلية، وأحصِ عدد الطلبات التي أرسلها فعليًا.

المبدأ بسيط: أبقِ طبقة واحدة فقط مسؤولة عن إعادة المحاولة في المسار نفسه، ودع الطبقات الأخرى تكتفي بنقل الحالة.

مشاهد البثّ تتطلب تصميمًا منفصلًا لاستراتيجية استعادة OpenAI API 429

إذا واجه طلب البثّ رمز 429 أثناء إنشاء الاتصال وقبل إخراج أي محتوى، فيمكن التعامل معه كطلب عادي. أما بعد بدء الإخراج، فينبغي ترك قرار «إعادة الإرسال» لمنطق العمل. مثلاً: إبلاغ المستخدم بوضوح بأنّ عملية التوليد قد انقطعت وترك خيار إعادة التوليد له؛ أو تجاهل الجزء الذي أُخرج بالفعل واستبداله بالكامل. لا تُعِد الإرسال بصمت في الخلفية، حتى لا تظهر فقرة مكررة مرتين على الواجهة.

عند الانتقال إلى منصات أخرى، لا تنسخ دلالات 429 الخاصة بـ OpenAI حرفيًا

تصنيف الأخطاء وقيم error.code وسلوك Retry-After ورؤوس الاستجابة الموصوفة في هذه المقالة كلها دلالات خاصة بـ OpenAI API الرسمي. وإذا استدعيت النموذج عبر بوابة طرف ثالث أو خدمة وكيل API أو منصة تجميع (مثل APIYI)، فإن أكواد الأخطاء وأبعاد تحديد المعدل وتوصيات إعادة المحاولة لدى الطرف الآخر يجب أن تُؤخذ من وثائق تلك المنصة نفسها، مع التحقق منها بشكل مستقل، وعدم نسخ سلوك OpenAI مباشرةً. والطريقة الأكثر أمانًا هي بناء طبقة لتوحيد الأخطاء في طبقة الربط، بحيث تُعيَّن رموز 429 الواردة من مصادر مختلفة إلى الحالات الثلاث المذكورة في هذه المقالة: «الانتظار وإعادة المحاولة / حظر الحساب / الفشل»، ثم تُسلَّم إلى وحدة إعادة المحاولة الموحدة للمعالجة.

تغييرات تستحق المراقبة المستمرة

توثيق أكواد الخطأ وتوثيق حدود المعدل في OpenAI قيد صيانة مستمرة. قد تتغير مستويات الحصص وأبعاد القياس وحقول رؤوس الاستجابة. ننصح بالاحتفاظ في الشفرة بسجل للنص الأصلي للخطأ، ومراجعة منطق الحكم بشكل دوري مقابل التوثيق الرسمي. كذلك، لا تكتب «كل خطأ 429 يُحل بالانتظار» في أي إعداد افتراضي. إذا صار هذا الافتراض فعّالًا عند نفاد الحصة، فالثمن قائمة مهام تدور بلا فائدة طوال الليل.

openai-api-429-should-you-keep-retrying-ar-image-3


في جوهره، 429 يعني أن الخادم يقول «تمهّل»، وأحيانًا يقول أيضًا «هذا الطريق مسدود مؤقتًا». التمييز بين الحالتين، ثم اختيار الانتظار أو التعديل أو التوقف، أهم من أي خوارزمية إعادة محاولة بارعة. وكما جاء في «المحاورات» (لون يو · تسي لو):

«لا تستعجل، ولا تنظر إلى المكاسب الصغيرة. من يستعجل لا يصل، ومن ينظر إلى المكاسب الصغيرة لا ينجز الأمور الكبيرة.»

موضوعات ذات صلة