Python requests：raise_for_status() 与 4xx/5xx 异常层次详解

Python requests：raise_for_status() 与 4xx/5xx 异常层次详解

在使用 Python 的 requests 库调用 HTTP 接口时，很多人会写出这样的代码：

resp = requests.post(f"{self.base_url}/chat/completions", headers=headers, json=payload)
resp.raise_for_status()

然后心里冒出一串问号：

• raise_for_status() 到底是干嘛的？
• 如果它抛异常，对调用者有什么影响？
• 4xx/5xx 到底算哪一层异常？
• 为什么 requests.post() 自己不抛异常，非要我再调一个方法？

这篇文章就把这些问题一次性讲清楚。

一、raise_for_status() 是什么？

raise_for_status() 是 requests.Response 对象的一个方法，作用非常单纯：

检查 HTTP 响应状态码，如果是 4xx 或 5xx，就抛出 requests.exceptions.HTTPError。

它的行为可以概括为：

• 状态码是 1xx、2xx、3xx ：什么都不做，返回 None。
• 状态码是 4xx、5xx ：抛出 requests.exceptions.HTTPError。
• 它不会自动重试，也不会自动解析响应体，只是"状态码不对就抛异常"。

大致等价于：

if 400 <= resp.status_code < 600:
    raise requests.exceptions.HTTPError(..., response=resp)

所以，它其实是把 HTTP 状态码错误"翻译"成 Python 异常，方便你用 try/except 统一处理。

二、不调用它会怎样？requests.post() 的默认行为

关键点来了：

requests.post() 默认不会因为 HTTP 状态码是 4xx/5xx 就抛异常。

也就是说，下面这段代码：

resp = requests.post(...)   # 正常执行，resp 是 Response 对象
print(resp.status_code)     # 404
resp.raise_for_status()     # 这里才抛出 HTTPError
print("这行不会执行")        # 如果上面抛了且没捕获，就不会执行

即使服务端返回 404、500，requests.post() 也会正常返回一个 Response 对象，代码继续往下走。

对 requests 来说，4xx/5xx 仍然是"成功的 HTTP 请求"------请求发出去了，服务器也响应了，只是状态码表示业务或应用层错误。

真正检查状态码并抛异常的是 resp.raise_for_status()。

如果你不调用它，那么：

resp = requests.post(...)
print(resp.status_code)  # 404 / 500 都能打印
data = resp.json()       # 可能成功，也可能因为响应体不是 JSON 而失败
# 代码继续执行

你可能会拿到一个错误页面的 HTML，然后 resp.json() 抛 JSONDecodeError，或者拿到一个带有错误信息的 JSON，但状态码明明是 500。这些都需要你自己判断。

三、4xx/5xx 到底属于哪一层异常？

这是最容易混淆的地方。我们分层来看：

层次	典型问题	在 requests 中的表现
网络/传输层	DNS 解析失败、连接被拒、TCP 断开、超时	requests.exceptions.ConnectionError、Timeout 等，在 requests.post() 时就抛出
HTTP 应用层	404、401、429、500、502、503 等	服务器已经正常返回了 HTTP 响应，只是状态码表示错误；默认不抛异常
库抽象层	raise_for_status() 主动检查状态码	4xx/5xx 被转成 requests.exceptions.HTTPError
业务层	响应体里的 {"code": 1001, "msg": "余额不足"}	需要你自己解析 resp.json() 后判断

所以：

• 4xx/5xx 属于 HTTP 协议层面的应用层错误。
• 4xx 表示客户端侧错误，比如参数错、未认证、无权限、限流。
• 5xx 表示服务端侧错误，比如内部异常、网关错误、服务不可用。
• 它们不是 TCP/IP 或网络连接异常，因为此时请求已经到达服务器，服务器也返回了响应。
• requests 默认不把 4xx/5xx 当异常，只把它当作普通响应。
• 只有调用 resp.raise_for_status()，才会把它包装成 requests.exceptions.HTTPError，这时它才变成 Python 异常。

一句话：

4xx/5xx 是 HTTP 应用层的状态码，不是网络层异常；HTTPError 是 requests 库对这类状态码的异常封装。

四、抛出异常后对调用者有什么影响？

如果 raise_for_status() 抛出了 HTTPError，且当前调用链没有 try/except 捕获，那么：

1. 当前函数立即中断

   resp = requests.post(...)
   resp.raise_for_status()
   data = resp.json()   # 如果上面抛异常，这里不会执行

2. 异常向上传播

   如果当前函数没有捕获，异常会传给调用当前函数的人；如果一直没人捕获，最终会导致程序、线程或异步任务失败，并打印 traceback。

   比如在 Web 框架里，可能直接变成 500 错误；在 Celery 任务里，任务会失败。

3. 调用者可以捕获并处理

   try:
       resp = requests.post(url, headers=headers, json=payload, timeout=10)
       resp.raise_for_status()
       data = resp.json()
   except requests.exceptions.HTTPError as e:
       print("HTTP 错误:", e.response.status_code)
       print("响应内容:", e.response.text)
   except requests.exceptions.RequestException as e:
       print("请求失败，如超时/连接错误:", e)

   捕获后，调用者可以决定重试、降级、返回错误信息，或者包装成自定义异常。

4. 只影响 HTTP 状态码错误

   连接失败、DNS 错误、超时等，通常在 requests.post() 时就抛 ConnectionError、Timeout 等，不会等到 raise_for_status()。

   JSON 解析失败则在 resp.json() 时抛。

五、代码示例：三种处理方式对比

1. 不调用 raise_for_status()，4xx/5xx 不会抛异常

resp = requests.post(...)
print(resp.status_code)  # 404 / 500 都能打印
data = resp.json()       # 可能成功，也可能因为响应体不是 JSON 而失败
# 代码继续执行

2. 调用 raise_for_status()，4xx/5xx 会抛异常

resp = requests.post(...)
resp.raise_for_status()  # 404 / 500 在这里抛 HTTPError
print("不会执行")

3. 捕获异常后可以继续

try:
    resp = requests.post(...)
    resp.raise_for_status()
    data = resp.json()
except requests.exceptions.HTTPError as e:
    print("HTTP 错误:", e.response.status_code)
    # 这里处理后，try/except 外面的代码可以继续执行

六、最佳实践建议

1. 始终设置超时

   requests.post(..., timeout=10)

   避免网络问题导致线程卡死。

2. 在 API 客户端边界统一调用 raise_for_status()

   把 4xx/5xx 转成异常，方便上层统一处理。但记得捕获后转换成业务层能理解的错误。

3. 区分网络异常和 HTTP 异常

   • 网络异常：ConnectionError、Timeout，通常需要重试或降级。
   • HTTP 异常：HTTPError，通常需要看状态码和响应体，决定是提示用户、刷新 token 还是重试。
   • 业务异常：响应体里的 code，需要业务代码自己判断。

4. 不要忽略响应体

   raise_for_status() 抛出的 HTTPError 对象带有 response 属性，可以读取 e.response.status_code 和 e.response.text，这对排查问题非常有用。

5. 注意 raise_for_status() 不会自动重试

   它只是检查状态码，重试逻辑需要你自己实现，比如用 tenacity 或手写循环。

七、总结

• raise_for_status() 用来检查 HTTP 状态码，4xx/5xx 时抛出 requests.exceptions.HTTPError。
• requests.post() 默认不会因为 4xx/5xx 抛异常，它会正常返回 Response 对象，代码继续执行。
• 4xx/5xx 属于 HTTP 应用层 错误，不是网络传输层异常。
• 网络层异常（连接失败、超时）在 requests.post() 时就抛出；HTTP 应用层异常需要 raise_for_status() 主动触发。
• 抛出异常后，如果没人捕获，调用链会中断；如果调用者捕获了，就可以读取 e.response 来做错误处理。
• 实际项目中，建议在 API 客户端边界捕获它，并转换成业务层能理解的错误。

理解这些分层，能帮你写出更健壮的 HTTP 调用代码，避免把"服务器返回 500"和"网络连不上"混为一谈。