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

Terapkan python requests retry dengan Session, HTTPAdapter, dan kebijakan urllib3 Retry, lalu atur timeout eksplisit pada setiap panggilan. Pertimbangkan keamanan pengulangan request, jumlah percobaan, dan kecepatan yang ditetapkan server dalam satu rancangan yang sama.

Mulailah dari skrip yang sudah diuji di bawah ini. Uji singkat kami pada 16 Oktober 2026 menunjukkan apa yang terjadi pada kegagalan lokal yang terkendali, termasuk 503 yang menetap dan tetap menjadi kegagalan setelah setiap retry.


Fakta Utama

  • urllib3 Retry yang dipasang pada HTTPAdapter menambahkan retry ke setiap panggilan dalam requests.Session.
  • Endpoint dengan urutan 503, 503, 200 berhasil pada percobaan ke-3 setelah 1,2 s dalam uji lokal kami.
  • Respons 429 dengan Retry-After: 2 menunggu tepat 2,0 s sebelum retry.
  • Endpoint yang gagal terus-menerus berhenti setelah 6 percobaan dan 15,7 s, bukan berulang tanpa akhir.
  • POST tidak di-retry secara default; tambahkan hanya untuk panggilan yang idempoten.
  • Tenacity menyediakan pola yang sama untuk fungsi apa pun, dengan setiap waktu tunggu dicatat dalam log.

Bagaimana cara menerapkan Python Requests Retry?

Pasang adapter dengan konfigurasi retry untuk HTTP dan HTTPS, lalu lakukan panggilan melalui Session tersebut. Ini adalah requests_retry.py yang sudah kami uji; jalankan server lokal yang ditampilkan di bawah sebelum menjalankannya.

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 tidak me-retry koneksi yang gagal secara default. Session menyimpan pengaturan dan menggunakan ulang koneksi; HTTPAdapter yang dipasang meneruskan kebijakan retry ke urllib3. Lihat penggunaan lanjutan Requests.

Skrip pengukuran ini mencetak respons akhir, termasuk yang berupa error. Dalam kode aplikasi, panggil raise_for_status() sebelum memakai hasil yang berhasil dan tangani kegagalan akhir RequestException pada batas pemanggil. Panggilan reset adalah persiapan lokal dan tidak memiliki timeout eksplisit; jangan menyalin kelalaian itu ke panggilan jarak jauh. Lihat penanganan error Requests.


Kegagalan apa yang sebaiknya ditangani Python Requests Retry?

Lakukan retry pada kegagalan yang masuk akal dapat hilang sendiri, dan hanya bila mengulang operasi tersebut dapat diterima. Gunakan pemeriksaan keamanan retry 4 langkah ini sebelum memilih pengaturan.

Sebelum sebuah request dicoba ulang

  • Langkah 1: Klasifikasikan kegagalan. Bedakan kegagalan koneksi, kegagalan pembacaan, dan respons HTTP. Daftar status kandidat kami adalah 429, 500, 502, 503, dan 504; tinjau daftar ini terhadap kontrak endpoint.
  • Langkah 2: Periksa keamanan pengulangan. Tentukan apakah request tambahan dapat menggandakan operasi tulis atau efek samping lainnya.
  • Langkah 3: Anggarkan percobaan dan waktu. Tetapkan jumlah panggilan maksimum, waktu tunggu yang dapat diterima, dan batas waktu pemanggil sebelum mengaktifkan retry.
  • Langkah 4: Hormati kecepatan dari server. Patuhi Retry-After dan hentikan atau tunda pekerjaan bila waktu tunggu yang diminta melebihi anggaran Anda.

Jangan menjadikan retry sebagai solusi untuk segala masalah. Selidiki respons 403 dan error autentikasi proxy 407 secara terpisah. Strategi python requests retry sebaiknya tetap menjaga kondisi akses dan aturan data yang berlaku.


Bagaimana cara kerja exponential backoff dan jitter?

Exponential backoff menambah jeda setelah kegagalan berulang; jitter menambahkan keacakan. Pada konfigurasi kami, jeda dasarnya adalah 0, 1, 2, 4, dan 8 detik.

Untuk retry ke-k, dimulai dari 1, backoff pertama urllib3 adalah nol; jeda berikutnya memakai backoff_factor * 2**(k-1). Jitter seragam ditambahkan dari nol hingga backoff_jitter, dengan batas backoff_max. Referensi urllib3 2.0.7 mendokumentasikan kontrol ini.

Lingkungan kami memakai urllib3 2.0.7, yang menerima backoff_jitter. Sesuaikan contoh dengan versi yang Anda pasang, jangan berasumsi sudah kompatibel. Ubah faktor untuk mengatur pertumbuhan jeda dan rentang jitter untuk menyebarkan retry; kebijakan waktu tunggu khusus sebaiknya ditempatkan pada lapisan retry yang dipilih dengan sengaja.

Hasil flaky 1,20 detik yang teramati mencerminkan satu undian acak dan overhead eksekusi lokal. Angka itu tidak memprediksi latensi API Anda.


Bagaimana menangani 429 dan Retry-After?

Patuhi nilai Retry-After yang valid sebelum mencoba lagi, kecuali operasi harus dihentikan. Header ini menerima delay-seconds atau HTTP-date, seperti dijelaskan di referensi Retry-After MDN.

Dengan penanganan header diaktifkan, urllib3 memakai jeda Retry-After yang positif sebelum backoff hasil perhitungannya. Tanpa jeda positif yang dapat dipakai, exponential backoff berlaku; header yang salah format memerlukan penanganan error eksplisit. Lihat perilaku sleep urllib3.

Respons 429 lokal kami meminta dua detik, dan percobaan berikutnya berhasil setelah 2,00 detik. Skrip ini tidak menerapkan batas waktu keseluruhan: jika server meminta waktu tunggu lebih lama daripada yang diizinkan operasi Anda, hentikan atau jadwalkan ulang, jangan mempersingkat waktu tunggu yang diminta. Rencanakan perilaku itu bersama kebijakan pembatasan laju API Anda.


Bagaimana timeout koneksi dan pembacaan memengaruhi retry?

Timeout membatasi satu tahap penantian tertentu, bukan seluruh operasi. Pembuatan koneksi, pembacaan respons, percobaan berulang, dan backoff semuanya menambah waktu yang berlalu.

Pada timeout=(3.05, 10), nilai pertama mengatur penantian koneksi dan nilai kedua mengatur ketiadaan aktivitas saat membaca. Keduanya bukan batas waktu jam dinding; Requests juga tidak memiliki timeout default. Lihat semantik timeout Requests.

Anggaran lima retry kami mengizinkan enam percobaan. Penghitung koneksi dan pembacaan membatasi kategori kegagalannya masing-masing dalam anggaran keseluruhan itu, bukan menambah jatah ekstra. Kontrol anggaran Retry mencakup total=0 untuk mencegah retry (per Oktober 2026).

Jangan berasumsi bahwa setiap kegagalan pembacaan body akan diulang. Kode sumber adapter Requests meneruskan preload_content=False; kegagalan saat body dibaca kemudian dapat terjadi di luar siklus retry adapter. Uji body yang terputus secara terpisah, dan terapkan batas waktu yang ketat pada batas aplikasi yang mampu menghentikan operasi.


Amankah me-retry request POST?

Timeout pada POST saja tidak cukup untuk memastikan pengulangan aman. Server mungkin sudah menyelesaikan operasi tulis sebelum klien kehilangan responsnya.

Ulangi hanya bila API mendokumentasikan perilaku idempoten atau mekanisme deduplikasi yang mencakup operasi tersebut. Gunakan kembali identitas operasi dan payload yang sama di bawah kontrak itu; menambahkan header idempotensi sembarang tidak menciptakan jaminan. Hal ini mengikuti pertimbangan pengulangan dalam spesifikasi idempotensi HTTP.

Kumpulan metode default urllib3 tidak menyertakan POST. Kumpulan kami yang lebih sempit hanya mengizinkan GET, HEAD, dan OPTIONS untuk retry status dan pembacaan; penyaringan metode bukan larangan menyeluruh terhadap retry koneksi sebelum pengiriman. Lihat metode Retry dan kategori kegagalan. Pertahankan contoh ini tetap fokus pada operasi baca.


Bagaimana mencatat percobaan dan mendiagnosis retry yang habis?

Catat kategori kegagalan, nomor percobaan, waktu tunggu yang dipilih, waktu yang berlalu, dan hasil akhir. Gunakan label rute yang sudah dibersihkan, bukan URL lengkap.

Skrip ini mengaktifkan log diagnostik untuk request localhost yang tidak berbahaya. Sebelum menyesuaikannya, hapus komponen URL yang sensitif dari log dan exception; contoh Tenacity menyertakan URL dalam pesan exception. Jangan pernah mencatat kredensial, header otorisasi, atau body respons yang bersifat privat.

503 yang menetap pada uji kami tetap berupa respons karena raise_on_status=False. Kegagalan transport tetap dapat memunculkan exception; Requests menerjemahkan kegagalan di bawahnya menjadi tipe seperti ConnectionError, ConnectTimeout, dan RetryError. Nilai integer pada max_retries juga tidak mengekspresikan kebijakan status eksplisit seperti yang ditunjukkan di sini. Lihat implementasi adapter.

Pastikan panggilan memakai Session yang Anda konfigurasi dan mount yang sesuai. Tutup Session setelah selesai, dan selidiki kegagalan khusus jaringan dengan panduan pemecahan masalah proxy. Hindari menambahkan perulangan retry kedua di sekitar klien yang sudah melakukan retry.


Kapan sebaiknya memakai urllib3 Retry, Tenacity, atau backoff?

Pilih satu lapisan yang mengelola retry. Gunakan konfigurasi transport untuk kebijakan HTTP dan pembungkus fungsi bila hasil aplikasi menentukan apakah pekerjaan perlu diulang.

Opsi Gunakan X bila… Hindari X bila…
urllib3 Retry Gunakan urllib3 Retry bila kebijakan transport dan status sudah sesuai. Hindari urllib3 Retry bila mengulang seluruh alur kerja aplikasi.
Tenacity Gunakan Tenacity bila hasil, exception, atau coroutine khusus menentukan retry. Hindari Tenacity bila membungkus klien yang sudah melakukan retry tanpa mengoordinasikan anggaran.
backoff Gunakan backoff bila kebijakan berbasis decorator sudah sesuai. Hindari backoff bila mengharapkan klasifikasi status HTTP otomatis tanpa konfigurasi.

Retry memusatkan penyaringan HTTP. Tenacity memisahkan kebijakan retry, wait, dan stop, mendukung retry coroutine, dan menyediakan callback logging. stop_after_attempt miliknya menghitung panggilan, termasuk yang pertama (per Oktober 2026). Lihat dokumentasi Tenacity dan referensi kebijakan wait.

tenacity_retry.py yang sudah kami uji mengulang GET flaky yang sama dengan pengaturan waktu berbeda. Skrip ini tidak setara untuk 429: ia tidak memeriksa 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")

Di sini, status yang dipilih diubah menjadi exception, waktu tunggu memakai exponential jitter, dan setelah percobaan habis exception terakhir dimunculkan kembali. Kategori exception koneksi yang luas perlu ditinjau sesuai endpoint masing-masing.

Sebagai perbandingan, backoff menggabungkan on_exception atau on_predicate dengan generator wait; jitter default yang didokumentasikannya adalah full jitter. Penyaringan status memerlukan predicate atau kebijakan exception dari Anda. max_tries miliknya membatasi total panggilan (per Oktober 2026). Lihat repositori resmi backoff. Kami tidak mengukur backoff.


Apa yang ditunjukkan oleh uji retry singkat yang dapat direproduksi?

Uji singkat kami pada 16 Oktober 2026 memperlihatkan pemulihan, penantian sesuai arahan server, dan percobaan yang habis. Ini adalah cuplikan kecil, bukan benchmark.

Andrii menjalankan Linux, Python 3.12, requests 2.31.0, urllib3 2.0.7, dan tenacity 9.1.4. Sumbernya: requests_retry.py, tenacity_retry.py, dan retry_server.py, yang ditampilkan ulang di sini. Sampelnya adalah satu kali eksekusi per endpoint dengan urllib3 dan satu kali eksekusi endpoint flaky dengan Tenacity, dengan penghitung lokal direset di antara skrip. Seluruh lalu lintas tetap berada di 127.0.0.1.

Kebijakan dan endpoint Status akhir Percobaan Waktu berlalu
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 mencatat waktu tunggu 1,36 dan 2,45 detik. Pengaturan wait yang berbeda menjelaskan selisih waktunya; pengamatan ini tidak dapat dipakai untuk memeringkat pustaka. Tidak ada percobaan berulang, klien bersamaan, koneksi jarak jauh, atau kegagalan timeout yang terukur.

Jalankan retry_server.py di satu terminal, lalu setiap klien secara terpisah di terminal lain:

# 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()

Bandwidth tidak diukur. Untuk perencanaan, perkirakan byte yang ditransfer dengan menjumlahkan byte request, respons, dan protokol di seluruh percobaan; enam pertukaran berukuran sama akan memakan biaya sekitar enam kali satu pertukaran, tetapi body error yang sebenarnya berbeda-beda.

Simulasi dengan seed di masa mendatang dapat membandingkan jitter khusus dengan kebijakan pustaka pada anggaran percobaan yang identik, dengan mencatat latensi, tabrakan penjadwalan, dan probabilitas keberhasilan simulasi. Itu akan menjadi metrik simulasi, terpisah dari tabel hasil pengamatan ini.


Pertanyaan yang Sering Diajukan

Apakah Python Requests melakukan retry secara otomatis?

Tidak secara default untuk koneksi yang gagal. Konfigurasikan adapter dengan sengaja, lalu verifikasi perilakunya terhadap kegagalan yang terkendali.

Bagaimana Session, HTTPAdapter, dan urllib3 Retry bekerja bersama?

Session memilih adapter yang dipasang untuk URL request. Adapter meneruskan kebijakan retry ke panggilan transport urllib3.

Bagaimana jeda exponential backoff dihitung?

Faktor 0,5 pada uji kami menghasilkan waktu tunggu dasar 0, 1, 2, 4, dan 8 detik. Jitter memengaruhi waktu tunggu berikutnya, sehingga eksekusi berulang tidak harus sama dengan waktu yang terukur.

Bagaimana Python sebaiknya menangani 429 dan Retry-After?

Tunggu sesuai permintaan bila operasi mampu menanggungnya. Jika tidak, hentikan atau tunda operasi, jangan mencoba lebih awal.

Amankah me-retry POST setelah timeout?

Timeout membuat hasil operasi tulis menjadi tidak pasti. Syaratkan jaminan pengulangan khusus API sebelum mengirimnya lagi.

Apakah skrip ini menerapkan batas waktu keseluruhan?

Tidak. Kebijakan percobaan dan timeout per panggilan di dalamnya tidak menetapkan batas waktu ketat.


Butuh proxy bersama kebijakan retry Anda?

Jika beban kerja Anda yang sah memerlukan perutean proxy, tinjau opsi proxy untuk Python Requests dan residential proxy DataImpulse. DataImpulse menyediakan proxy, bukan API scraping, unblocker terkelola, VPN, atau dataset. Tetapkan keputusan pengulangan, pengaturan laju, dan penanganan kegagalan di klien Anda.

Terakhir diperbarui: 16 Oktober 2026.


Share article: