A maioria dos códigos com proxy tem um único caminho de erro — capturar tudo, rotacionar, tentar novamente — e esse caminho único é o motivo pelo qual os pools se esgotam e os alvos escalam. Uma requisição via proxy que falha é um de cinco eventos diferentes: o proxy em si estava inacessível; o proxy recusou suas credenciais; o alvo recusou este IP; o alvo limitou sua taxa; ou o alvo respondeu 200 com uma página de desafio em vez de conteúdo. Rotacionar ajuda com exatamente um desses. Tentar novamente imediatamente não ajuda com nenhum. Este guia classifica as falhas e, em seguida, constrói uma camada compacta de retry em Python que responde a cada uma corretamente, com backoff exponencial, rotação apenas onde se aplica e um circuit breaker para que um alvo que disse “pare” seja realmente deixado em paz. Os trechos usam requests; a lógica é portada diretamente para httpx e aiohttp (nomes de parâmetros em Proxies em Python).
As cinco falhas
| # | O que aconteceu | Como aparece em Python | Resposta correta |
|---|---|---|---|
| 1 | Proxy inacessível — host/porta errados, indisponibilidade do provedor, rede | ProxyError envolvendo um erro de conexão; ConnectTimeout antes de qualquer HTTP | Tente novamente com backoff; após N falhas, marque o endpoint do proxy como inativo e alerte. A rotação dentro do mesmo gateway não ajudará se o gateway estiver inativo. |
| 2 | Proxy rejeitou você — credenciais inválidas, IP não autorizado, plano esgotado | ProxyError com 407; às vezes 4xx específico do provedor vindo do gateway | Não tente novamente. Corrija a configuração; tentar novamente um 407 em loop pode fazer sua conta ser limitada pelo provedor. |
| 3 | Alvo recusou este IP — reputação, ASN, bloqueio geográfico | 403, às vezes 401/451; ocasionalmente um reset de conexão | Rotacione para uma nova saída (novo ID de sessão) e um novo cookie jar; tente novamente uma ou duas vezes; se persistir entre IPs, o problema é fingerprint ou tipo, não o IP — pare e reavalie (porquê). |
| 4 | Alvo limitou sua taxa | 429, ou 503 com Retry-After | Durma Retry-After (ou backoff) nesta saída; depois continue nela. Rotacionar em vez de esperar espalha o bloqueio. Veja sinais de limite de taxa. |
| 5 | Desafio servido como 200 — página CAPTCHA/intersticial | Status 200, mas o corpo não é o conteúdo esperado | Trate como falha tipo 3. Detecte pelo conteúdo (texto marcador, elemento esperado ausente, corpo muito pequeno), nunca apenas pelo status. |
| — | Rede transitória / 5xx do alvo | ReadTimeout, ConnectionError no meio do fluxo, 500/502/504 | Tente novamente com backoff na mesma saída; geralmente não é sobre você. |
A tabela é o artigo inteiro; tudo abaixo é fazer um programa obedecê-la.
Classifique primeiro
import requests
from enum import Enum
class Fail(Enum):
NONE = 0; PROXY_DOWN = 1; PROXY_AUTH = 2; IP_BLOCKED = 3; RATE_LIMITED = 4; CHALLENGE = 5; TRANSIENT = 6
CHALLENGE_MARKERS = (b"captcha", b"cf-chl", b"challenge-platform", b"datadome", b"px-captcha")
def classify(resp: requests.Response | None, exc: Exception | None, min_bytes: int = 2000) -> Fail:
if exc is not None:
if isinstance(exc, requests.exceptions.ProxyError):
return Fail.PROXY_AUTH if "407" in str(exc) else Fail.PROXY_DOWN
if isinstance(exc, (requests.exceptions.ConnectTimeout,)):
return Fail.PROXY_DOWN # nunca alcançou o proxy (ou ele nunca respondeu ao CONNECT)
if isinstance(exc, (requests.exceptions.ReadTimeout, requests.exceptions.ConnectionError)):
return Fail.TRANSIENT
return Fail.TRANSIENT
s = resp.status_code
if s == 429 or (s == 503 and "Retry-After" in resp.headers):
return Fail.RATE_LIMITED
if s in (401, 403, 451):
return Fail.IP_BLOCKED
if s >= 500:
return Fail.TRANSIENT
if s == 200:
body = resp.content[:20000].lower()
if len(resp.content) < min_bytes or any(m in body for m in CHALLENGE_MARKERS):
return Fail.CHALLENGE
return Fail.NONE
return Fail.TRANSIENT
Ajuste CHALLENGE_MARKERS e min_bytes por alvo: a verificação confiável é “a página contém o elemento que vim buscar?” — um título de produto, uma chave JSON — e sua ausência é o sinal de desafio.
Backoff, feito corretamente
Backoff exponencial com jitter: dobrar os atrasos espalha as tentativas; o jitter impede que cem workers tentem novamente em sincronia. Respeite Retry-After quando existir.
import random, time, email.utils
def backoff_delay(attempt: int, base: float = 1.0, cap: float = 60.0) -> float:
return random.uniform(0, min(cap, base * (2 ** attempt))) # "jitter total"
def retry_after_seconds(resp: requests.Response | None) -> float | None:
if resp is None or "Retry-After" not in resp.headers:
return None
v = resp.headers["Retry-After"].strip()
if v.isdigit():
return float(v)
dt = email.utils.parsedate_to_datetime(v) # forma de data HTTP
return max(0.0, dt.timestamp() - time.time()) if dt else None
Um circuit breaker por (alvo, saída)
Quando um alvo recusou uma saída várias vezes seguidas, pare de oferecer essa saída para esse alvo por um tempo, em vez de descobrir o bloqueio a cada requisição. Mesma ideia para um endpoint de proxy que está inativo.
import time
from collections import defaultdict
class Breaker:
def __init__(self, threshold=3, cooldown=300):
self.fail = defaultdict(int); self.open_until = {}
self.threshold, self.cooldown = threshold, cooldown
def allow(self, key) -> bool:
return time.time() >= self.open_until.get(key, 0)
def ok(self, key):
self.fail[key] = 0
def bad(self, key):
self.fail[key] += 1
if self.fail[key] >= self.threshold:
self.open_until[key] = time.time() + self.cooldown
self.fail[key] = 0
Juntando tudo
import secrets
GATE, PORT, PASS = "gate.provider.com", 7777, "PASSWORD"
breaker = Breaker()
def proxies_for(session_id: str) -> dict:
url = f"http://customer-session-{session_id}:{PASS}@{GATE}:{PORT}"
return {"http": url, "https": url}
def fetch(url: str, host: str, max_attempts: int = 5, timeout=(10, 30)) -> requests.Response | None:
sid = secrets.token_hex(4)
sess = requests.Session()
for attempt in range(max_attempts):
key = (host, sid)
if not breaker.allow(key) or not breaker.allow(("gateway", GATE)):
sid = secrets.token_hex(4); sess = requests.Session(); continue # escolha uma saída diferente
resp = exc = None
try:
resp = sess.get(url, proxies=proxies_for(sid), timeout=timeout)
except requests.RequestException as e:
exc = e
kind = classify(resp, exc)
if kind is Fail.NONE:
breaker.ok(key); breaker.ok(("gateway", GATE)); return resp
if kind is Fail.PROXY_AUTH:
raise RuntimeError("proxy rejeitou credenciais/whitelist — corrija a config, não tente novamente")
if kind is Fail.PROXY_DOWN:
breaker.bad(("gateway", GATE)); time.sleep(backoff_delay(attempt, base=2)); continue
if kind is Fail.RATE_LIMITED:
time.sleep(retry_after_seconds(resp) or backoff_delay(attempt, base=5)); continue # mesma saída
if kind in (Fail.IP_BLOCKED, Fail.CHALLENGE):
breaker.bad(key)
sid = secrets.token_hex(4); sess = requests.Session() # nova saída + cookies novos
time.sleep(backoff_delay(attempt)); continue
# TRANSIENT
time.sleep(backoff_delay(attempt)); continue
return None
O que isso faz que o loop ingênuo não faz: nunca tenta novamente um 407; espera em limites de taxa em vez de pular; rotaciona apenas em recusas de nível de IP e desafios, e emparelha cada rotação com um novo cookie jar (mesmos cookies em um novo IP é o mesmo visitante); para de oferecer uma saída que continua falhando em um host; e faz backoff com jitter em todos os lugares. Conecte as contagens de Fail às suas métricas — uma taxa crescente de IP_BLOCKED em diferentes saídas significa que o fingerprint ou o tipo de IP está errado, e nenhuma política de retry corrigirá isso (veja fingerprinting TLS e escolhendo o tipo de IP).
Usando uma biblioteca em vez disso
tenacity fornece decoradores para condições de retry/backoff/parada e é uma boa base — mas mantenha a classificação e a decisão “rotacionar vs esperar vs parar” em seu próprio código; bibliotecas genéricas de retry tratam todas as exceções da mesma forma, que é exatamente o erro. O objeto Retry do urllib3 (montável em um HTTPAdapter do requests) lida bem com retries de nível de conexão e Retry-After para 429/503, e vale a pena usar para as classes TRANSIENT e RATE_LIMITED; ele não pode rotacionar seu proxy ou detectar um corpo de desafio, então complementa em vez de substituir a camada acima.
Nota sobre async
Em aiohttp/httpx.AsyncClient a estrutura é idêntica com await asyncio.sleep(); a única adição é um semáforo por host para que o backoff em um host não atrase os outros, e para que a concorrência por host permaneça educada. Um semáforo global sozinho permite que cem corrotinas se acumulem em um único alvo no momento em que ele é o único que não está dormindo.
Perguntas frequentes
Devo rotacionar o proxy a cada erro?
Não. Rotacione em recusas de nível de IP (classe 403) e páginas de desafio, sempre com um novo cookie jar. Espere — não rotacione — em 429/Retry-After. Corrija a configuração em 407. Tente novamente a mesma saída em erros transitórios e 5xx.
Quantas vezes devo tentar novamente?
Três a cinco tentativas com backoff exponencial e jitter é o envelope usual; além disso, você está enfrentando um bloqueio persistente (limite de rotação atingido) ou uma indisponibilidade (o breaker deve estar aberto). Limite o tempo total de parede por requisição.
Como detecto uma página CAPTCHA no código?
Pelo conteúdo, não pelo status: verifique o elemento que você espera (um título, uma chave JSON), marcadores de desafio conhecidos no corpo e uma resposta implausivelmente pequena. Um 200 sem seu conteúdo é uma falha.
O que é um circuit breaker para proxies?
Um contador por (alvo, saída) que, após várias falhas consecutivas, para de usar essa saída para esse alvo por um período de resfriamento — para que você não descubra o bloqueio a cada requisição e não continue martelando um host que o recusou.
Por que não usar apenas tenacity ou urllib3 Retry?
Use-os para retries transitórios e de limite de taxa; mas eles não podem distinguir um 407 de um 403 de um desafio, não podem rotacionar seu ID de sessão e não podem redefinir cookies. Mantenha essa lógica de decisão em seu código.
O que significa uma taxa de bloqueio crescente em muitos IPs?
Que os IPs não são o problema: o alvo está identificando você por fingerprint TLS/HTTP, cabeçalhos ou comportamento, ou o tipo de IP está errado para aquele site. Pare de rotacionar e corrija a camada que está realmente falhando.