首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >requests 自动重试怎么配:urllib3 Retry 的退避时间、状态码、POST 和 Retry-After 实测

requests 自动重试怎么配:urllib3 Retry 的退避时间、状态码、POST 和 Retry-After 实测

原创
作者头像
用户12904616
发布于 2026-11-20 10:24:53
发布于 2026-11-20 10:24:53
110
举报

先说结论: requests 默认不重试。要重试,给 HTTPAdapter 传一个 urllib3 的 Retry 对象,挂到 Session 上。有五件事最容易配错或误解:

  1. 退避时间:urllib3 2.x 第一次重试不等待,之后按 backoff_factor × 2^(n-1) 增长。backoff_factor=0.5 时,各次重试前的等待依次是 0、1、2、4 秒,上限默认 120 秒;
  2. 状态码重试要显式打开:只有写进 status_forcelist 的状态码才会重试;
  3. POST 默认不重试:allowed_methods 的默认值里没有 POST 和 PATCH,因为它们不是幂等的;
  4. Retry-After 默认会被遵守:413、429、503 带了这个头时,按它说的时间等;
  5. 重试用完后,状态码类的失败抛 RetryError,连接类的失败抛 ConnectionError;设 raise_on_status=False 则返回最后一次的响应。

下面在本地用一个按路径模拟各种失败的服务端,把这几点逐个跑一遍。环境:Python 3.12、requests 2.34.2、urllib3 2.8.0。

测试服务端

服务端打印每个请求到达的相对时间,这样可以直接从日志里算出每次重试之间等了多久。

代码语言:javascript
复制
# flaky.py
import time
from collections import Counter
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

T0 = time.monotonic()
hits = Counter()

class H(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"
    def reply(self, code, extra=None):
        body = f"{code}\n".encode()
        self.send_response(code)
        for k, v in (extra or {}).items():
            self.send_header(k, v)
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)
    def handle_any(self):
        if self.command == "POST":
            self.rfile.read(int(self.headers.get("Content-Length", 0)))
        hits[self.path] += 1
        n = hits[self.path]
        print(f"[server] {time.monotonic() - T0:6.2f}s  {self.command} {self.path} 第{n}次", flush=True)
        if self.path == "/flaky":                 # 前 3 次 503,第 4 次成功
            self.reply(503 if n <= 3 else 200)
        elif self.path == "/always503":
            self.reply(503)
        elif self.path == "/retry-after":         # 第 1 次 503,并要求 2 秒后再来
            self.reply(503, {"Retry-After": "2"}) if n == 1 else self.reply(200)
        elif self.path == "/post-flaky":          # 第 1 次 503,之后成功
            self.reply(503 if n == 1 else 200)
        elif self.path == "/notfound":
            self.reply(404)
    do_GET = do_POST = handle_any
    def log_message(self, *a): pass

ThreadingHTTPServer(("127.0.0.1", 18103), H).serve_forever()

客户端配置

代码语言:javascript
复制
import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry

retry = Retry(
    total=4,                                        # 最多重试 4 次(不含第一次请求)
    backoff_factor=0.5,                             # 退避:0、1、2、4 秒
    status_forcelist=[500, 502, 503, 504],          # 这些状态码也重试
    allowed_methods=Retry.DEFAULT_ALLOWED_METHODS,  # 默认值,写出来是为了醒目:不含 POST
)
s = requests.Session()
adapter = HTTPAdapter(max_retries=retry)
s.mount("http://", adapter)
s.mount("https://", adapter)

s.mount 按网址前缀匹配,http 和 https 两个前缀要分别挂,只挂一个的话另一类请求不会重试。

实验一:前几次失败,最后成功

代码语言:javascript
复制
GET /flaky: HTTP 200,3.0s

[server]   1.07s  GET /flaky 第1次
[server]   1.07s  GET /flaky 第2次
[server]   2.09s  GET /flaky 第3次
[server]   4.09s  GET /flaky 第4次

第 1 次 503 后立刻重试,间隔 0;第 2 次 503 后等了 1 秒;第 3 次后等了 2 秒;第 4 次成功。调用方只看到一个 200,总耗时 3 秒。

退避时间的计算在 urllib3 的 Retry.get_backoff_time() 里:只统计最近一段连续的失败次数 n,n 小于等于 1 时返回 0,否则返回 backoff_factor * 2 ** (n - 1),再和 backoff_max(默认 120 秒)取较小值。如果你看的是旧资料,会发现公式描述不完全一样,以自己安装版本的源码为准。

多个客户端同时失败、又按同样的节奏重试,会在同一时刻一起打到服务端上。urllib3 2.x 提供了 backoff_jitter 参数,在退避时间上加一个随机量,把重试打散:

代码语言:javascript
复制
Retry(total=4, backoff_factor=0.5, backoff_jitter=0.3, status_forcelist=[502, 503, 504])

实验二:一直失败

代码语言:javascript
复制
GET /always503: RetryError: HTTPConnectionPool(host='127.0.0.1', port=18103): Max retries exceeded with url: /always503 (Caused by ResponseError('too many 503 error responses')),7.0s

[server]   4.18s  GET /always503 第1次
[server]   4.18s  GET /always503 第2次
[server]   5.19s  GET /always503 第3次
[server]   7.20s  GET /always503 第4次
[server]  11.20s  GET /always503 第5次

1 次请求 + 4 次重试,共 5 次,等待 0 + 1 + 2 + 4 = 7 秒,最后抛出 requests.exceptions.RetryError。注意这不是 HTTPError,原来写的 except requests.HTTPError 接不住它。

如果你希望重试用完后拿到最后一次的响应自己处理,而不是异常:

代码语言:javascript
复制
Retry(total=4, backoff_factor=0.5, status_forcelist=[503], raise_on_status=False)
代码语言:javascript
复制
GET /always503 raise_on_status=False: 503 7.0s

同样等了 7 秒,返回的是一个普通的 503 响应,可以照常读取状态码和响应体。

实验三:服务端要求「2 秒后再来」

代码语言:javascript
复制
GET /retry-after: HTTP 200,2.0s

[server]  11.29s  GET /retry-after 第1次
[server]  13.30s  GET /retry-after 第2次

按退避公式,第一次重试本应立即发生,实际却等了 2 秒,因为响应里带了 Retry-After: 2。respect_retry_after_header 默认为 True,作用于 RETRY_AFTER_STATUS_CODES,即 413、429、503 三个状态码。

这一点要特别注意:如果服务端回了 Retry-After: 3600,客户端就会真的等一个小时。 线程被占住,调用方以为程序卡死了。对外部接口,可以考虑:

  • 设 respect_retry_after_header=False,完全由自己的退避控制;
  • 或者保留遵守,但在外层给整个调用加一个总时限,超时就放弃。

还要注意 backoff_max 只限制退避时间,不限制 Retry-After 给出的等待时间。

实验四:POST 不重试

代码语言:javascript
复制
POST /post-flaky: HTTP 503,0.0s

[server]  13.39s  POST /post-flaky 第1次

服务端只收到 1 次请求,客户端直接拿到了 503。默认的 allowed_methods 是:

代码语言:javascript
复制
frozenset(["HEAD", "GET", "PUT", "DELETE", "OPTIONS", "TRACE"])

POST 和 PATCH 不在里面。原因很简单:服务端回 503 时,你无法确定它是「没处理」还是「处理到一半出错」。对下单、扣款、发消息这类操作,自动重发可能造成重复执行。

确实要让 POST 也重试,可以把 allowed_methods 设为 None(表示所有方法都重试)或者显式加上 POST:

代码语言:javascript
复制
POST allowed_methods=None: 200 0.0s

[server]   1.07s  POST /post-flaky 第1次
[server]   1.07s  POST /post-flaky 第2次

这样做的前提是接口本身是幂等的,最好由服务端支持幂等键:客户端为每个业务操作生成一个唯一 ID 放在请求头里,服务端发现同一个 ID 已经处理过,就直接返回上次的结果。

实验五:不在列表里的状态码,以及连接失败

代码语言:javascript
复制
GET /notfound: HTTP 404,0.0s
GET 没监听的端口: ConnectionError: HTTPConnectionPool(host='127.0.0.1', port=18105): Max retries exceeded with url: / (Caused by NewConnectionError("HTTPConnection(host='127.0.0.1', port=18105): Failed to establish a new connection: [Errno 61] Connection refused")),7.0s

404 不在 status_forcelist 里,直接返回,不重试。这是对的,404 重试多少次都是 404。同理,400、401、403 也不应该放进去。

连接被拒绝时,这次真的重试了 4 次,同样按 0、1、2、4 秒退避,7 秒后抛出 ConnectionError。连接类错误受 connect 参数和 total 共同限制,total 用完就停。如果你想区分「连不上」和「服务端报错」的重试次数,可以分别设置:

代码语言:javascript
复制
Retry(total=None, connect=3, read=1, status=4, backoff_factor=0.5,
      status_forcelist=[502, 503, 504])

read 控制的是「请求已经发出、读取响应时出错」的重试。对非幂等请求,这种情况下服务端很可能已经处理过了,read 设小一点或设为 0 更安全。

推荐配置

代码语言:javascript
复制
import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry

def make_session():
    retry = Retry(
        total=4,
        connect=3,
        read=1,
        status=3,
        backoff_factor=0.5,
        backoff_jitter=0.3,
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=Retry.DEFAULT_ALLOWED_METHODS,
        respect_retry_after_header=True,
        raise_on_status=False,
    )
    adapter = HTTPAdapter(max_retries=retry)
    s = requests.Session()
    s.mount("http://", adapter)
    s.mount("https://", adapter)
    return s

session = make_session()
resp = session.get("https://example.com/api", timeout=(3.05, 10))

再强调一次:重试不能代替超时。 每次尝试都要有自己的 timeout,否则一次卡住的读取就会让后面的重试永远没有机会执行。

参数

默认值

作用

total

10(requests 默认不重试,是因为它传的是 0)

所有重试次数的总上限

connect / read / status

None(只受 total 限制)

分别限制各类错误的重试次数

backoff_factor

0

退避基数,0 表示不等待

backoff_max

120

单次退避上限(秒)

backoff_jitter

0.0

随机附加的等待时间上限

status_forcelist

None

哪些状态码要重试

allowed_methods

不含 POST、PATCH

哪些方法可以重试

respect_retry_after_header

True

是否遵守 413/429/503 的 Retry-After

raise_on_status

True

用完后抛 RetryError 还是返回最后的响应

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 测试服务端
  • 客户端配置
  • 实验一:前几次失败,最后成功
  • 实验二:一直失败
  • 实验三:服务端要求「2 秒后再来」
  • 实验四:POST 不重试
  • 实验五:不在列表里的状态码,以及连接失败
  • 推荐配置
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档