Bu makalede
Python requests retry mekanizmasını bir Session, bir HTTPAdapter ve bir urllib3 Retry politikasıyla uygulayın, ardından her çağrıya açık timeout değerleri verin. Yeniden gönderim güvenliğini, deneme sayılarını ve sunucunun belirlediği hızı aynı tasarımda birlikte ele alın.
Aşağıdaki test edilmiş betiklerle başlayın. 16 Ekim 2026 tarihli hızlı denememiz, kontrollü yerel hatalara karşı neler olduğunu gösteriyor. Buna, her yeniden denemeden sonra da hata olarak kalan kalıcı bir 503 yanıtı da dahil.
Temel Bilgiler
- Bir HTTPAdapter üzerine bağlanan urllib3 Retry, bir requests.Session içindeki her çağrıya yeniden deneme ekler.
- 503, 503, 200 yanıtı veren bir endpoint, yerel testimizde 1,2 sn sonra 3. denemede başarılı oldu.
- Retry-After: 2 içeren bir 429 yanıtı, yeniden denemeden önce tam olarak 2,0 sn bekledi.
- Sürekli hata veren bir endpoint, sonsuz döngüye girmek yerine 6 denemeden ve 15,7 sn sonra durdu.
- POST varsayılan olarak yeniden denenmez; yalnızca idempotent çağrılar için ekleyin.
- Tenacity, her bekleme kaydedilerek herhangi bir fonksiyon için aynı kalıbı sunar.
Python Requests Retry nasıl uygulanır?
Hem HTTP hem de HTTPS için yeniden deneme yapılandırılmış bir adapter bağlayın, ardından çağrıları bu Session üzerinden yapın. Aşağıdaki, test ettiğimiz requests_retry.py dosyasıdır; çalıştırmadan önce daha ileride gösterilen yerel sunucuyu başlatın.
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, başarısız bağlantıları varsayılan olarak yeniden denemez. Bir Session ayarları korur ve bağlantıları havuzlar; üzerine bağlanan HTTPAdapter ise yeniden deneme politikasını urllib3’e iletir. Bkz. Requests gelişmiş kullanım.
Bu ölçüm betiği, hatalar dahil son yanıtı yazdırır. Uygulama kodunda, başarılı bir sonucu kullanmadan önce raise_for_status() çağırın ve kalıcı RequestException hatalarını çağıran tarafın sınırında ele alın. Reset çağrısı yerel bir kurulum adımıdır ve açık bir timeout değeri yoktur; bu eksikliği uzak çağrılara kopyalamayın. Bkz. Requests hata yönetimi.
Python Requests Retry hangi hataları ele almalı?
Yalnızca ortadan kalkma ihtimali makul olan hataları ve ancak işlemin tekrarlanması kabul edilebilir olduğunda yeniden deneyin. Ayarları seçmeden önce bu 4 adımlı yeniden deneme güvenlik kontrolünü kullanın.

- Adım 1: Hatayı sınıflandırın. Bağlantı hatalarını, okuma hatalarını ve HTTP yanıtlarını birbirinden ayırın. Aday durum listemiz 429, 500, 502, 503 ve 504’tür; bunu endpoint’in sözleşmesiyle karşılaştırarak gözden geçirin.
- Adım 2: Yeniden gönderim güvenliğini kontrol edin. Bir isteğin daha gönderilmesinin bir yazma işlemini ya da başka bir yan etkiyi çoğaltıp çoğaltmayacağına karar verin.
- Adım 3: Deneme ve süre bütçesi belirleyin. Yeniden denemeleri açmadan önce en fazla çağrı sayısını, kabul edilebilir bekleme süresini ve çağıranın son tarihini tanımlayın.
- Adım 4: Sunucunun belirlediği hıza uyun. Retry-After değerine saygı gösterin; gereken bekleme bütçenizi aşıyorsa işi durdurun ya da erteleyin.
Yeniden denemeleri her soruna çare olarak kullanmayın. 403 yanıtlarını ve 407 proxy kimlik doğrulama hatalarını ayrıca inceleyin. Bir python requests retry stratejisi, erişim koşullarını ve geçerli veri kurallarını korumalıdır.
Üstel backoff ve jitter nasıl çalışır?
Üstel backoff, tekrarlanan hatalardan sonra gecikmeyi artırır; jitter ise rastgelelik ekler. Yapılandırmamızda temel bekleme süreleri 0, 1, 2, 4 ve 8 saniyeydi.
1’den başlayan k numaralı yeniden deneme için urllib3’ün ilk backoff değeri sıfırdır; sonraki gecikmeler backoff_factor * 2**(k-1) formülünü kullanır. Sıfırdan backoff_jitter değerine kadar düzgün dağılımlı bir jitter ekleyin; bu değer backoff_max ile sınırlandırılır. urllib3 2.0.7 referansı bu denetimleri belgelemektedir.
Ortamımızda backoff_jitter parametresini kabul eden urllib3 2.0.7 kullanıldı. Uyumluluğu varsaymak yerine örneği kurulu sürümünüzle eşleştirin. Büyümeyi ayarlamak için çarpanı, yeniden denemeleri dağıtmak için jitter aralığını değiştirin; özel bir bekleme politikası, bilinçli olarak seçilmiş bir yeniden deneme katmanına aittir.
Gözlemlenen 1,20 saniyelik flaky sonucu tek bir rastgele çekimi ve yerel çalışma yükünü yansıtır. API’nizin gecikmesini öngörmez.
429 ve Retry-After nasıl ele alınmalı?
İşlem durdurulmak zorunda değilse, yeniden denemeden önce geçerli bir Retry-After değerine uyun. Başlık, saniye cinsinden gecikmeyi ya da bir HTTP tarihini kabul eder; bunu MDN’nin Retry-After referansı açıklar.
Başlık işleme açıkken urllib3, hesapladığı backoff yerine pozitif bir Retry-After gecikmesini kullanır. Kullanılabilir pozitif bir gecikme yoksa üstel backoff uygulanır; hatalı biçimlendirilmiş başlıklar için açık hata yönetimi gerekir. Bkz. urllib3’ün sleep davranışı.
Yerel 429 yanıtımız iki saniye bekleme istedi ve sonraki deneme 2,00 saniye sonra başarılı oldu. Betikte genel bir son tarih denetimi yoktur: sunucu, işleminizin izin verdiğinden daha uzun bir bekleme istiyorsa, istenen beklemeyi kısaltmak yerine işlemi durdurun ya da yeniden planlayın. Bu davranışı API hız sınırlama politikanızla birlikte planlayın.
Bağlantı ve okuma timeout değerleri yeniden denemeleri nasıl etkiler?
Bir timeout, tüm işlemi değil, belirli bir bekleme aşamasını sınırlar. Bağlantı kurma, yanıt okuma, tekrarlanan denemeler ve backoff, geçen toplam süreye katkıda bulunur.
timeout=(3.05, 10) ifadesinde ilk değer bağlantı beklemesini, ikinci değer ise okuma sırasındaki hareketsizliği denetler. İkisi de gerçek zaman (wall-clock) cinsinden bir son tarih değildir; ayrıca Requests’in varsayılan bir timeout değeri yoktur. Bkz. Requests timeout anlamları.
Beş yeniden denemelik bütçemiz altı denemeye izin verdi. Bağlantı ve okuma sayaçları, ek hak tanımak yerine, bu genel bütçe içinde kendi hata kategorilerini sınırlar. Retry bütçe denetimleri, yeniden denemeleri engellemek için total=0 değerini içerir (Ekim 2026 itibarıyla).
Her gövde okuma hatasının yeniden oynatılacağını varsaymayın. Requests adapter kaynak kodu preload_content=False değerini iletir; gövdenin sonradan tüketilmesi sırasındaki hatalar adapter’ın yeniden deneme döngüsünün dışında gerçekleşebilir. Yarıda kesilen gövdeleri ayrıca test edin ve katı bir son tarihi, işlemi durdurabilen bir uygulama sınırında uygulayın.
POST isteklerini güvenle yeniden deneyebilir misiniz?
Tek başına bir POST timeout’u, yeniden göndermenin güvenli olduğunu kanıtlayamaz. İstemci yanıtı kaybetmeden önce sunucu yazma işlemini tamamlamış olabilir.
Yalnızca API, işlemi kapsayan idempotent davranışı ya da bir tekilleştirme mekanizmasını belgelediğinde yeniden gönderin. Bu sözleşme kapsamında aynı işlem kimliğini ve aynı yükü kullanın; rastgele bir idempotency başlığı eklemek garanti oluşturmaz. Bu, HTTP’nin idempotency belirtimindeki yeniden gönderim değerlendirmelerini izler.
urllib3’ün varsayılan yöntem kümesi POST’u içermez. Bizim daha dar kümemiz, durum ve okuma yeniden denemeleri için GET, HEAD ve OPTIONS’a izin verir; yöntem filtrelemesi, iletimden önceki bağlantı yeniden denemelerine yönelik genel bir yasak değildir. Bkz. Retry yöntem ve hata kategorileri. Bu örneği okuma işlemlerine odaklı tutun.
Denemeleri nasıl kaydeder ve tükenen yeniden denemeleri nasıl teşhis edersiniz?
Hata kategorisini, deneme numarasını, seçilen beklemeyi, geçen süreyi ve nihai sonucu kaydedin. Tam bir URL yerine temizlenmiş bir rota etiketi kullanın.
Betikler, zararsız localhost istekleri için tanılama günlüğünü etkinleştirir. Bunları uyarlamadan önce günlüklerden ve istisnalardan hassas URL bileşenlerini kaldırın; Tenacity örneği, URL’sini bir istisna mesajına dahil eder. Kimlik bilgilerini, yetkilendirme başlıklarını veya özel yanıt gövdelerini asla kaydetmeyin.
Kalıcı 503 yanıtımız, raise_on_status=False olduğu için bir yanıt olarak kaldı. Taşıma katmanı hataları yine de istisna fırlatabilir; Requests, alttaki hataları ConnectionError, ConnectTimeout ve RetryError gibi türlere çevirir. Tam sayı olarak verilen bir max_retries değeri de burada gösterilen açık durum politikasını ifade etmez. Bkz. adapter uygulaması.
Çağrıların yapılandırdığınız Session’ı ve eşleşen mount’u kullandığını kontrol edin. İşiniz bittiğinde kapatın ve ağa özgü hataları proxy sorun giderme rehberiyle inceleyin. Zaten yeniden deneme yapan bir istemcinin etrafına ikinci bir yeniden deneme döngüsü eklemekten kaçının.
urllib3 Retry, Tenacity veya backoff ne zaman kullanılmalı?
Yeniden denemelerin sahibi olacak tek bir katman seçin. HTTP politikası için taşıma yapılandırmasını, işin tekrarlanıp tekrarlanmayacağına uygulama sonuçları karar veriyorsa bir fonksiyon sarmalayıcısını kullanın.
| Seçenek | X şu durumlarda kullanılır | X şu durumlarda kullanılmaz |
|---|---|---|
| urllib3 Retry | Taşıma ve durum politikası uygunsa urllib3 Retry kullanın. | Uygulama iş akışının tamamı yeniden denenecekse urllib3 Retry kullanmayın. |
| Tenacity | Yeniden denemeleri özel sonuçlar, istisnalar veya coroutine’ler yönlendiriyorsa Tenacity kullanın. | Bütçeleri koordine etmeden, zaten yeniden deneme yapan bir istemciyi sarmalayacaksanız Tenacity kullanmayın. |
| backoff | Decorator tabanlı bir politika uygunsa backoff kullanın. | Yapılandırma olmadan otomatik HTTP durum sınıflandırması bekliyorsanız backoff kullanmayın. |
Retry, HTTP filtrelemesini merkezileştirir. Tenacity; yeniden deneme, bekleme ve durdurma politikalarını ayırır, coroutine yeniden denemelerini destekler ve günlük geri çağrıları sunar. stop_after_attempt değeri, ilk çağrı dahil çağrıları sayar (Ekim 2026 itibarıyla). Bkz. Tenacity belgeleri ve bekleme politikası referansı.
Test ettiğimiz tenacity_retry.py, aynı flaky GET isteğini farklı zamanlamayla tekrarlar. 429 için eşdeğer değildir: Retry-After başlığını incelemez.
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")
Burada seçilen durum kodları istisnaya dönüşür, beklemeler üstel jitter kullanır ve deneme hakkı tükendiğinde son istisna yeniden fırlatılır. Geniş kapsamlı bağlantı istisnası kategorisi, endpoint’e özgü bir incelemeye ihtiyaç duyar.
Karşılaştırma için backoff, on_exception veya on_predicate ile bir bekleme üreticisini birleştirir; belgelenmiş varsayılan jitter değeri full jitter’dır. Durum filtrelemesi için kendi predicate’inize ya da istisna politikanıza ihtiyaç vardır. max_tries değeri toplam çağrıları sınırlar (Ekim 2026 itibarıyla). Bkz. resmi backoff deposu. backoff’u ölçmedik.
Hızlı ve tekrarlanabilir bir yeniden deneme testi ne gösteriyor?
16 Ekim 2026 tarihli hızlı denememiz toparlanmayı, sunucunun yönlendirdiği beklemeyi ve deneme hakkının tükenmesini gösterdi. Bu küçük bir anlık görüntüdür, bir kıyaslama (benchmark) değildir.
Andrii; Linux, Python 3.12, requests 2.31.0, urllib3 2.0.7 ve tenacity 9.1.4 kullandı. Kaynaklar: burada yeniden verilen requests_retry.py, tenacity_retry.py ve retry_server.py. Örneklem, urllib3 ile her endpoint için bir çalıştırma ve Tenacity ile flaky endpoint için bir çalıştırmadan oluştu; yerel sayaçlar betikler arasında sıfırlandı. Tüm trafik 127.0.0.1 üzerinde kaldı.
| Politika ve endpoint | Son durum | Deneme | Geçen süre |
|---|---|---|---|
| urllib3 /ok | 200 | 1 | 0,00 sn |
| urllib3 /flaky | 200 | 3 | 1,20 sn |
| urllib3 /limited | 200 | 2 | 2,00 sn |
| urllib3 /down | 503 | 6 | 15,69 sn |
| Tenacity /flaky | 200 | 3 | 3,82 sn |
Tenacity, 1,36 ve 2,45 saniyelik beklemeler kaydetti. Zamanlama farkını farklı bekleme ayarları açıklar; bu gözlemlerle kütüphaneler sıralanamaz. Tekrarlanan denemeler, eşzamanlı istemciler, uzak bağlantılar veya ölçülmüş timeout hataları yoktu.
retry_server.py dosyasını bir terminalde, ardından her istemciyi ayrı ayrı başka bir terminalde çalıştırın:
# 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()
Bant genişliği ölçülmedi. Planlama için aktarılan baytları, denemeler boyunca istek, yanıt ve protokol baytlarını toplayarak tahmin edin; eşit boyutlu altı alışveriş kabaca tek bir alışverişin altı katına mal olur, ancak gerçek hata gövdeleri farklılık gösterir.
Gelecekte tohumlu (seeded) bir simülasyon, özel jitter’ı kütüphane politikalarıyla aynı deneme bütçeleri altında karşılaştırabilir; gecikmeyi, zamanlama çakışmalarını ve simüle edilmiş başarı olasılığını kaydedebilir. Bunlar, gözlemlenen bu tablodan ayrı, simüle edilmiş metrikler olurdu.
Sık Sorulan Sorular
Python Requests otomatik olarak yeniden dener mi?
Başarısız bağlantılar için varsayılan olarak denemez. Adapter’ı bilinçli şekilde yapılandırın, ardından davranışı kontrollü bir hataya karşı doğrulayın.
Session, HTTPAdapter ve urllib3 Retry birlikte nasıl çalışır?
Session, istek URL’si için kendisine bağlanmış adapter’ı seçer. Adapter, yeniden deneme politikasını urllib3’ün taşıma çağrılarına iletir.
Üstel backoff gecikmeleri nasıl hesaplanır?
0,5 çarpanımız 0, 1, 2, 4 ve 8 saniyelik temel beklemeler üretti. Jitter sonraki beklemeleri etkilediği için tekrarlanan çalıştırmaların ölçülen sürelerle aynı çıkması gerekmez.
Python, 429 ve Retry-After değerini nasıl ele almalı?
İşlem karşılayabiliyorsa istenen süre kadar bekleyin. Aksi halde işlemi daha erken yeniden denemek yerine durdurun veya erteleyin.
Timeout sonrasında bir POST isteğini yeniden denemek güvenli midir?
Bir timeout, yazma işleminin sonucunu belirsiz bırakır. İsteği tekrar göndermeden önce API’ye özgü bir yeniden gönderim garantisi isteyin.
Bu betikler genel bir son tarih uyguladı mı?
Hayır. Deneme politikaları ve çağrı başına timeout değerleri, katı bir geçen süre sınırı oluşturmaz.
Yeniden deneme politikanızın yanında bir proxy mi gerekiyor?
Yetkili iş yükünüz proxy yönlendirmesi gerektiriyorsa, Python Requests için proxy seçeneklerini ve DataImpulse residential proxy’lerini inceleyin. DataImpulse proxy sağlar; bir scraping API’si, yönetilen unblocker, VPN veya veri seti sunmaz. Yeniden gönderim kararlarını, hız ayarını ve hata yönetimini kendi istemcinizde tutun.
Son güncelleme: 16 Ekim 2026.
