La mayoría del código de proxy tiene una única ruta de error: capturar todo, rotar, reintentar — y esa ruta única es la razón por la que los pools se agotan y los objetivos escalan. Una solicitud fallida a través de proxy es uno de cinco eventos diferentes: el proxy en sí no estaba disponible; el proxy rechazó tus credenciales; el objetivo rechazó esta IP; el objetivo te limitó la tasa; o el objetivo respondió con un 200 pero con una página de desafío en lugar del contenido. Rotar ayuda exactamente con uno de esos. Reintentar inmediatamente no ayuda con ninguno. Esta guía clasifica los fallos y luego construye una capa compacta de reintentos en Python que responde a cada uno correctamente, con backoff exponencial, rotación solo donde aplica, y un circuit breaker para que un objetivo que ha dicho "basta" sea dejado en paz. Los fragmentos usan requests; la lógica se traslada directamente a httpx y aiohttp (nombres de parámetros en Proxies en Python).
Los cinco fallos
| # | Qué pasó | Cómo se muestra en Python | Respuesta correcta |
|---|---|---|---|
| 1 | Proxy inalcanzable — host/puerto incorrecto, caída del proveedor, red | ProxyError que envuelve un error de conexión; ConnectTimeout antes de cualquier HTTP | Reintentar con backoff; después de N fallos, marcar el endpoint del proxy como caído y alertar. Rotar dentro del mismo gateway no ayudará si el gateway está caído. |
| 2 | El proxy te rechazó — credenciales incorrectas, IP no permitida, plan agotado | ProxyError con 407; a veces 4xx específicos del proveedor desde el gateway | No reintentar. Corregir la configuración; reintentar un 407 en un bucle puede hacer que el proveedor limite tu cuenta. |
| 3 | El objetivo rechazó esta IP — reputación, ASN, bloqueo geográfico | 403, a veces 401/451; ocasionalmente un reset de conexión | Rotar a una nueva salida (nuevo ID de sesión) y un nuevo cookie jar; reintentar una o dos veces; si persiste entre IPs, el problema es la huella digital o el tipo, no la IP — detente y reevalúa (por qué). |
| 4 | El objetivo te limitó la tasa | 429, o 503 con Retry-After | Dormir Retry-After (o backoff) en esta salida; luego continuar en ella. Rotar en lugar de esperar extiende el bloqueo. Ver señales de límite de tasa. |
| 5 | Desafío servido como 200 — página CAPTCHA/intersticial | Estado 200 pero el cuerpo no es el contenido esperado | Tratar como fallo tipo 3. Detectarlo por contenido (texto marcador, elemento esperado ausente, cuerpo demasiado pequeño), nunca solo por el estado. |
| — | Red transitoria / 5xx del objetivo | ReadTimeout, ConnectionError a mitad de flujo, 500/502/504 | Reintentar con backoff en la misma salida; estos generalmente no son por ti. |
La tabla es todo el artículo; todo lo demás es hacer que un programa la obedezca.
Clasificar primero
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 llegó al proxy (o nunca respondió 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
Ajusta CHALLENGE_MARKERS y min_bytes por objetivo: la verificación confiable es "¿la página contiene el elemento que vine a buscar?" — un título de producto, una clave JSON — y su ausencia es la señal de desafío.
Backoff, hecho correctamente
Backoff exponencial con jitter: duplicar los retrasos distribuye los reintentos; el jitter evita que cien trabajadores reintenten al unísono. Respeta Retry-After cuando exista.
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))) # "full jitter"
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 HTTP-date
return max(0.0, dt.timestamp() - time.time()) if dt else None
Un circuit breaker por (objetivo, salida)
Cuando un objetivo ha rechazado una salida varias veces seguidas, deja de ofrecer esa salida a ese objetivo por un tiempo en lugar de descubrir el bloqueo en cada solicitud. Lo mismo para un endpoint de proxy que está caído.
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
Poniéndolo todo junto
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 # elige una salida 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("el proxy rechazó credenciales/lista blanca — corrige la configuración, no reintentes")
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 # misma salida
if kind in (Fail.IP_BLOCKED, Fail.CHALLENGE):
breaker.bad(key)
sid = secrets.token_hex(4); sess = requests.Session() # nueva salida + cookies frescas
time.sleep(backoff_delay(attempt)); continue
# TRANSIENT
time.sleep(backoff_delay(attempt)); continue
return None
Lo que esto hace que el bucle ingenuo no hace: nunca reintenta un 407; espera en los límites de tasa en lugar de saltar; rota solo en rechazos a nivel de IP y desafíos, y empareja cada rotación con un cookie jar fresco (las mismas cookies en una IP nueva es el mismo visitante); deja de ofrecer una salida que sigue fallando en un host; y hace backoff con jitter en todas partes. Conecta los contadores de Fail a tus métricas — una tasa creciente de IP_BLOCKED en diferentes salidas significa que la huella digital o el tipo de IP es incorrecto, y ninguna política de reintentos lo arreglará (ver huella digital TLS y elegir el tipo de IP).
Usar una biblioteca en su lugar
tenacity te da decoradores para condiciones de reintento/backoff/detención y es una buena base — pero mantén la clasificación y la decisión de "rotar vs esperar vs detener" en tu propio código; las bibliotecas genéricas de reintentos tratan todas las excepciones por igual, que es precisamente el error. El objeto Retry de urllib3 (montable en un HTTPAdapter de requests) maneja bien los reintentos a nivel de conexión y Retry-After para 429/503, y vale la pena usarlo para las clases TRANSIENT y RATE_LIMITED; no puede rotar tu proxy ni detectar un cuerpo de desafío, así que complementa en lugar de reemplazar la capa anterior.
Nota sobre async
En aiohttp/httpx.AsyncClient la estructura es idéntica con await asyncio.sleep(); la única adición es un semáforo por host para que el backoff en un host no detenga a los demás, y para que la concurrencia por host se mantenga educada. Un semáforo global solo permite que cien corrutinas se amontonen en un objetivo en el momento en que es el único que no está durmiendo.
Preguntas frecuentes
¿Debo rotar el proxy en cada error?
No. Rota en rechazos a nivel de IP (clase 403) y páginas de desafío, siempre con un cookie jar fresco. Espera — no rotes — en 429/Retry-After. Corrige la configuración en 407. Reintenta la misma salida en errores transitorios y 5xx.
¿Cuántas veces debo reintentar?
De tres a cinco intentos con backoff exponencial y jitter es el rango habitual; más allá de eso, o enfrentas un bloqueo persistente (límite de rotación alcanzado) o una caída (el breaker debería estar abierto). Limita el tiempo total de pared por solicitud.
¿Cómo detecto una página CAPTCHA en código?
Por contenido, no por estado: verifica el elemento que esperas (un título, una clave JSON), los marcadores de desafío conocidos en el cuerpo y una respuesta sospechosamente pequeña. Un 200 sin tu contenido es un fallo.
¿Qué es un circuit breaker para proxies?
Un contador por (objetivo, salida) que, después de varios fallos consecutivos, deja de usar esa salida para ese objetivo durante un período de enfriamiento — para que no redescubras el bloqueo en cada solicitud y no sigas golpeando a un host que te rechazó.
¿Por qué no usar simplemente tenacity o urllib3 Retry?
Úsalos para reintentos transitorios y de límite de tasa; pero no pueden distinguir un 407 de un 403 de un desafío, no pueden rotar tu ID de sesión y no pueden restablecer cookies. Mantén esa lógica de decisión en tu código.
¿Qué significa una tasa de bloqueo creciente en muchas IPs?
Que las IPs no son el problema: el objetivo te identifica por huella digital TLS/HTTP, headers o comportamiento, o el tipo de IP es incorrecto para ese sitio. Deja de rotar y arregla la capa que realmente está fallando.