Python Requests Retry flow showing failure classification, replay safety, retry budgets, and server pacing

طبّق إعادة المحاولة في Python Requests باستخدام Session مع HTTPAdapter وسياسة Retry من urllib3، ثم حدّد مهلة صريحة لكل استدعاء. اجعل أمان إعادة التنفيذ وعدد المحاولات ووتيرة الخادم ضمن التصميم نفسه.

ابدأ بالسكربتات المختبرة أدناه. يوضح تشغيلنا السريع في 16 أكتوبر 2026 ما حدث أمام أعطال محلية خاضعة للتحكم، ومنها الخطأ 503 الدائم الذي بقي فشلاً بعد كل إعادة محاولة.


أبرز الحقائق

  • إضافة urllib3 Retry إلى HTTPAdapter مثبّت يضيف إعادة المحاولة إلى كل استدعاء داخل requests.Session.
  • نجحت نقطة نهاية تعيد 503 ثم 503 ثم 200 في المحاولة 3 بعد 1.2 s في اختبارنا المحلي.
  • الاستجابة 429 مع Retry-After: 2 انتظرت بالضبط 2.0 s قبل إعادة المحاولة.
  • توقفت نقطة نهاية فاشلة بشكل دائم بعد 6 محاولات و15.7 s بدلاً من الدوران في حلقة لا تنتهي.
  • لا تُعاد محاولة POST افتراضياً؛ أضفه فقط للاستدعاءات متماثلة الأثر (idempotent).
  • توفر Tenacity النمط نفسه لأي دالة، مع تسجيل كل فترة انتظار.

كيف تطبّق إعادة المحاولة في Python Requests؟

ثبّت محوّلاً مهيأً لإعادة المحاولة لكل من HTTP وHTTPS، ثم أجرِ الاستدعاءات عبر هذه الجلسة (Session). هذا هو الملف الذي اختبرناه requests_retry.py؛ شغّل الخادم المحلي الموضح لاحقاً قبل تنفيذه.

import logging, time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

logging.basicConfig(level=logging.WARNING)
logging.getLogger("urllib3.connectionpool").setLevel(logging.DEBUG)  # shows each retry


def make_session(total=5, backoff=0.5):
    retry = Retry(
        total=total,                       # overall cap across all error types
        connect=3, read=2,                 # separate caps for connection and read failures
        status_forcelist=(429, 500, 502, 503, 504),
        allowed_methods=frozenset({"GET", "HEAD", "OPTIONS"}),  # never auto-retry POST
        backoff_factor=backoff,            # sleeps 0, 1, 2, 4 ... seconds (0.5 x 2^n, first retry immediate)
        backoff_jitter=0.3,                # random extra delay so many clients do not retry in sync
        respect_retry_after_header=True,   # wait what a 429/503 Retry-After says
        raise_on_status=False,             # return the last response instead of raising RetryError
    )
    s = requests.Session()
    adapter = HTTPAdapter(max_retries=retry)
    s.mount("http://", adapter)
    s.mount("https://", adapter)
    return s


if __name__ == "__main__":
    s = make_session()
    base = "http://127.0.0.1:8377"
    s.get(f"{base}/reset")
    for path in ("/ok", "/flaky", "/limited", "/down"):
        t = time.time()
        r = s.get(base + path, timeout=(3.05, 10))   # (connect, read) timeouts
        print(f"{path:9} -> {r.status_code} after {time.time() - t:.2f}s, body {r.text}")

لا يعيد Requests محاولة الاتصالات الفاشلة افتراضياً. تحتفظ Session بالإعدادات وتجمّع الاتصالات، ويمرر HTTPAdapter المثبّت عليها سياسة إعادة المحاولة إلى urllib3. راجع الاستخدام المتقدم لـ Requests.

يطبع سكربت القياس هذا الاستجابة النهائية بما فيها الأخطاء. في كود التطبيق، استدعِ raise_for_status() قبل استهلاك أي نتيجة ناجحة، وعالج حالات الفشل النهائية RequestException عند حدود الجهة المستدعية. استدعاء إعادة الضبط (reset) إعداد محلي ولا يتضمن مهلة صريحة؛ لا تنسخ هذا الإغفال إلى الاستدعاءات البعيدة. راجع معالجة الأخطاء في Requests.


ما حالات الفشل التي ينبغي أن تعالجها إعادة المحاولة في Python Requests؟

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

قبل إعادة محاولة الطلب

  • الخطوة 1: صنّف الفشل. فرّق بين إخفاقات الاتصال وإخفاقات القراءة واستجابات HTTP. قائمة الحالات المرشحة لدينا هي 429 و500 و502 و503 و504؛ راجعها وفق عقد نقطة النهاية.
  • الخطوة 2: تحقق من أمان إعادة التنفيذ. قرّر ما إذا كان طلب إضافي قد يكرر عملية كتابة أو أي أثر جانبي آخر.
  • الخطوة 3: حدّد ميزانية المحاولات والوقت. عيّن الحد الأقصى للاستدعاءات والانتظار المقبول ومهلة الجهة المستدعية قبل تفعيل إعادة المحاولة.
  • الخطوة 4: التزم بوتيرة الخادم. احترم Retry-After وأوقف العمل أو أجّله عندما يتجاوز الانتظار المطلوب ميزانيتك.

لا تستخدم إعادة المحاولة كعلاج شامل. تحرَّ استجابات 403 وأخطاء مصادقة البروكسي 407 بشكل منفصل. ينبغي لاستراتيجية إعادة المحاولة في Python Requests أن تحافظ على شروط الوصول وقواعد البيانات المعمول بها.


كيف يعمل التراجع الأسي والتشويش العشوائي (jitter)؟

يزيد التراجع الأسي مدة التأخير بعد كل إخفاق متكرر، بينما يضيف التشويش العشوائي عنصر عشوائية. في إعداداتنا كانت فترات الانتظار الأساسية 0 و1 و2 و4 و8 ثوانٍ.

بالنسبة لإعادة المحاولة رقم k بدءاً من 1، يكون أول تراجع في urllib3 صفراً؛ وتستخدم التأخيرات اللاحقة backoff_factor * 2**(k-1). ثم يُضاف تشويش منتظم من صفر إلى backoff_jitter، مع مراعاة backoff_max. توثّق مرجع urllib3 2.0.7 هذه الضوابط.

استخدمت بيئتنا urllib3 2.0.7 الذي يقبل backoff_jitter. طابق المثال مع النسخة المثبتة لديك ولا تفترض التوافق. غيّر المعامل للتحكم في سرعة النمو، وغيّر نطاق التشويش لتوزيع المحاولات؛ أما سياسة الانتظار المخصصة فمكانها طبقة إعادة محاولة تختارها عن قصد.

تعكس نتيجة الاستجابة المتقطعة المرصودة، وهي 1.20 s، سحبة عشوائية واحدة مع كلفة التنفيذ المحلي. وهي لا تتنبأ بزمن استجابة API الخاص بك.


كيف تتعامل مع 429 وRetry-After؟

احترم قيمة Retry-After الصالحة قبل المحاولة مجدداً، ما لم يكن يجب إيقاف العملية. يقبل الترويس إما عدد ثوانٍ وإما تاريخ HTTP، كما يوضح مرجع MDN لـ Retry-After.

عند تفعيل معالجة الترويس، يستخدم urllib3 قيمة Retry-After الموجبة بدلاً من التراجع المحسوب. وإذا لم توجد قيمة موجبة صالحة، يُطبَّق التراجع الأسي؛ أما الترويسات المشوهة فتحتاج إلى معالجة أخطاء صريحة. راجع سلوك الانتظار في urllib3.

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


كيف تؤثر مهلات الاتصال والقراءة على إعادة المحاولة؟

المهلة تحدّ مرحلة انتظار معينة، وليست العملية كاملة. فإنشاء الاتصال وقراءة الاستجابة والمحاولات المتكررة والتراجع كلها تسهم في الزمن المنقضي.

في timeout=(3.05, 10)، تتحكم القيمة الأولى في انتظار الاتصال وتتحكم الثانية في خمول القراءة. ولا تمثل أيٌّ منهما مهلة بالزمن الفعلي؛ كما أن Requests لا يملك مهلة افتراضية. راجع دلالات المهلة في Requests.

سمحت ميزانية إعادة المحاولة الخمس لدينا بست محاولات. وتقيّد عدّادات الاتصال والقراءة فئات الفشل الخاصة بها داخل تلك الميزانية الإجمالية، ولا تضيف حصصاً إضافية. وتتضمن ضوابط ميزانية Retry القيمة total=0 لمنع إعادة المحاولة (اعتباراً من أكتوبر 2026).

لا تفترض أن كل فشل في قراءة المحتوى تُعاد محاولته. فمصدر محوّل Requests يمرر preload_content=False؛ وقد تقع حالات الفشل أثناء استهلاك المحتوى لاحقاً خارج دورة إعادة المحاولة في المحوّل. اختبر المحتوى المنقطع بشكل منفصل، وفرض أي مهلة صارمة عند حد في التطبيق قادر على إيقاف العملية.


هل يمكن إعادة محاولة طلبات POST بأمان؟

لا تكفي مهلة POST وحدها لإثبات أن إعادة التنفيذ آمنة. فقد يكون الخادم أتمّ الكتابة قبل أن يفقد العميل الاستجابة.

أعد التنفيذ فقط عندما يوثّق API سلوكاً متماثل الأثر أو آلية لإزالة التكرار تغطي العملية. أعد استخدام هوية العملية والحمولة نفسهما ضمن ذلك العقد؛ فإضافة ترويسة تماثل أثر عشوائية لا تنشئ ضماناً. يتبع هذا اعتبارات إعادة التنفيذ في مواصفة تماثل الأثر في HTTP.

تستثني مجموعة الطرق الافتراضية في urllib3 الطريقة POST. وتسمح مجموعتنا الأضيق بـ GET وHEAD وOPTIONS لإعادة محاولات الحالة والقراءة؛ وتصفية الطرق ليست منعاً شاملاً لإعادة محاولة الاتصال قبل الإرسال. راجع طريقة Retry وفئات الفشل. أبقِ هذا المثال مركّزاً على عمليات القراءة.


كيف تسجّل المحاولات وتشخّص استنفاد إعادة المحاولة؟

سجّل فئة الفشل ورقم المحاولة ومدة الانتظار المختارة والزمن المنقضي والنتيجة النهائية. استخدم تسمية مسار منقّحة بدلاً من عنوان URL كامل.

تفعّل السكربتات التسجيل التشخيصي لطلبات localhost غير الضارة. قبل تكييفها، أزل مكونات URL الحساسة من السجلات والاستثناءات؛ فمثال Tenacity يضمّن URL في رسالة الاستثناء. لا تسجّل أبداً بيانات الاعتماد أو ترويسات التفويض أو محتوى الاستجابات الخاصة.

بقي الخطأ 503 الدائم لدينا استجابةً لأن raise_on_status=False. وقد تظل إخفاقات النقل ترفع استثناءات؛ إذ يترجم Requests الإخفاقات الأساسية إلى أنواع مثل ConnectionError وConnectTimeout وRetryError. كما أن القيمة الصحيحة في max_retries لا تعبّر عن سياسة الحالات الصريحة الموضحة هنا. راجع تنفيذ المحوّل.

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


متى تستخدم urllib3 Retry أو Tenacity أو backoff؟

اختر طبقة واحدة تتولى إعادة المحاولة. استخدم إعدادات النقل لسياسة HTTP، واستخدم غلاف الدالة عندما تحدد نتائج التطبيق ما إذا كان يجب تكرار العمل.

الخيار استخدم X عندما… تجنب X عندما…
urllib3 Retry استخدم urllib3 Retry عندما تناسب سياسة النقل والحالة احتياجك. تجنب urllib3 Retry عند إعادة محاولة سير عمل تطبيق كامل.
Tenacity استخدم Tenacity عندما تقود النتائج المخصصة أو الاستثناءات أو الدوال المتزامنة المشتركة (coroutines) إعادة المحاولة. تجنب Tenacity عند تغليف عميل يعيد المحاولة أصلاً دون تنسيق الميزانيات.
backoff استخدم backoff عندما تناسبك سياسة قائمة على المزخرفات (decorators). تجنب backoff عندما تتوقع تصنيفاً تلقائياً لحالات HTTP دون إعداد.

تركّز Retry تصفية HTTP في مكان واحد. أما Tenacity فتفصل بين سياسات إعادة المحاولة والانتظار والإيقاف، وتدعم إعادة محاولة الدوال المتزامنة المشتركة، وتوفر دوال استدعاء للتسجيل. ويحتسب stop_after_attempt فيها الاستدعاءات بما فيها الأول (اعتباراً من أكتوبر 2026). راجع توثيق Tenacity ومرجع سياسة الانتظار.

يكرر الملف الذي اختبرناه tenacity_retry.py طلب GET المتقطع نفسه بتوقيت مختلف. وهو ليس مكافئاً في حالة 429: فهو لا يفحص Retry-After.

import time
import requests
from tenacity import (retry, retry_if_exception_type, stop_after_attempt,
                      wait_exponential_jitter, before_sleep_log)
import logging
logging.basicConfig(level=logging.INFO, format="%(message)s")
log = logging.getLogger("retry")


class RetryableStatus(Exception):
    pass


@retry(
    retry=retry_if_exception_type((requests.ConnectionError, requests.Timeout, RetryableStatus)),
    wait=wait_exponential_jitter(initial=1, max=30, jitter=1),
    stop=stop_after_attempt(5),
    before_sleep=before_sleep_log(log, logging.INFO),
    reraise=True,
)
def get_json(url):
    r = requests.get(url, timeout=(3.05, 10))
    if r.status_code in (429, 500, 502, 503, 504):
        raise RetryableStatus(f"{r.status_code} from {url}")
    r.raise_for_status()
    return r.json()


if __name__ == "__main__":
    requests.get("http://127.0.0.1:8377/reset")
    t = time.time()
    print(get_json("http://127.0.0.1:8377/flaky"), f"{time.time() - t:.2f}s")

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

للمقارنة، تجمع backoff بين on_exception أو on_predicate ومولّد انتظار؛ والتشويش الافتراضي الموثّق فيها هو التشويش الكامل. وتصفية الحالات تتطلب دالة شرط أو سياسة استثناءات من عندك. ويحدّ max_tries فيها إجمالي الاستدعاءات (اعتباراً من أكتوبر 2026). راجع المستودع الرسمي لـ backoff. لم نقم بقياس backoff.


ماذا يُظهر تشغيل سريع لإعادة المحاولة يمكن إعادة إنتاجه؟

أظهر تشغيلنا السريع في 16 أكتوبر 2026 التعافي والانتظار الذي يحدده الخادم والاستنفاد. وهو لقطة صغيرة وليس اختبار أداء مرجعياً.

شغّل Andrii نظام Linux مع Python 3.12 وrequests 2.31.0 وurllib3 2.0.7 وtenacity 9.1.4. المصادر: requests_retry.py وtenacity_retry.py وretry_server.py، وهي معروضة هنا. كانت العينة تشغيلاً واحداً لكل نقطة نهاية مع urllib3 وتشغيلاً واحداً لنقطة النهاية المتقطعة مع Tenacity، مع إعادة ضبط العدّادات المحلية بين السكربتات. وبقيت كل حركة المرور على 127.0.0.1.

السياسة ونقطة النهاية الحالة النهائية المحاولات الزمن المنقضي
urllib3 /ok 200 1 0.00 s
urllib3 /flaky 200 3 1.20 s
urllib3 /limited 200 2 2.00 s
urllib3 /down 503 6 15.69 s
Tenacity /flaky 200 3 3.82 s

سجّلت Tenacity فترات انتظار بلغت 1.36 و2.45 ثانية. وتفسّر إعدادات الانتظار المختلفة فارق التوقيت؛ ولا يمكن لهذه الملاحظات ترتيب المكتبات. لم تُجرَ تجارب متكررة ولا عملاء متزامنون ولا اتصالات بعيدة، ولم تُقَس إخفاقات المهلة.

شغّل retry_server.py في طرفية واحدة، ثم شغّل كل عميل على حدة في طرفية أخرى:

# Local test server: /flaky fails with 503 twice then 200; /limited answers 429 + Retry-After: 2 once then 200.
import http.server, json, threading
hits = {}
class H(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        n = hits[self.path] = hits.get(self.path, 0) + 1
        if self.path == "/reset":
            hits.clear(); return self.send(200, {"reset": True})
        if self.path == "/flaky" and n <= 2: return self.send(503, {"attempt": n})
        if self.path == "/limited" and n == 1: return self.send(429, {"attempt": n}, {"Retry-After": "2"})
        if self.path == "/down": return self.send(503, {"attempt": n})
        self.send(200, {"ok": True, "attempt": n})
    def send(self, code, body, extra=None):
        self.send_response(code)
        for k, v in (extra or {}).items(): self.send_header(k, v)
        self.send_header("Content-Type", "application/json"); self.end_headers()
        self.wfile.write(json.dumps(body).encode())
    def log_message(self, *a): pass
http.server.ThreadingHTTPServer(("127.0.0.1", 8377), H).serve_forever()

لم يُقَس النطاق الترددي. وللتخطيط، قدّر البايتات المنقولة بجمع بايتات الطلب والاستجابة والبروتوكول عبر المحاولات؛ فست عمليات تبادل متساوية الحجم ستكلّف نحو ست أضعاف عملية واحدة، لكن أجسام الأخطاء الفعلية تختلف.

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


الأسئلة الشائعة

هل يعيد Python Requests المحاولة تلقائياً؟

ليس افتراضياً في حالة الاتصالات الفاشلة. هيّئ المحوّل عن قصد، ثم تحقق من السلوك أمام فشل خاضع للتحكم.

كيف تعمل Session وHTTPAdapter وurllib3 Retry معاً؟

تختار Session المحوّل المثبّت لديها وفق URL الطلب. ويمرر المحوّل سياسة إعادة المحاولة إلى استدعاءات النقل في urllib3.

كيف تُحسب تأخيرات التراجع الأسي؟

أنتج معاملنا 0.5 فترات انتظار أساسية بلغت 0 و1 و2 و4 و8 ثوانٍ. وأثّر التشويش على فترات الانتظار اللاحقة، لذا لا يلزم أن تطابق التشغيلات المتكررة الأزمنة المقيسة.

كيف ينبغي أن يتعامل Python مع 429 وRetry-After؟

انتظر كما هو مطلوب عندما تتحمل العملية ذلك. وإلا فأوقف العملية أو أجّلها بدلاً من إعادة المحاولة مبكراً.

هل إعادة محاولة POST بعد انتهاء المهلة آمنة؟

تترك المهلة نتيجة الكتابة غير مؤكدة. اشترط ضمان إعادة تنفيذ خاصاً بـ API قبل إرسالها مرة أخرى.

هل فرضت هذه السكربتات مهلة إجمالية؟

لا. فسياسات المحاولات والمهلات لكل استدعاء فيها لا تضع حداً صارماً للزمن المنقضي.


هل تحتاج إلى بروكسي إلى جانب سياسة إعادة المحاولة؟

إذا كان حمل العمل المصرّح به لديك يحتاج إلى توجيه عبر البروكسي، فراجع خيارات البروكسي لـ Python Requests وDataImpulse residential proxies. تقدّم DataImpulse بروكسيات فقط، وليست scraping API ولا أداة فك حظر مُدارة ولا VPN ولا مجموعة بيانات. أبقِ قرارات إعادة التنفيذ والوتيرة ومعالجة الأخطاء في عميلك.

آخر تحديث: 16 أكتوبر 2026.


Share article: