应显式捕获requests.exceptions.requestexception，配合timeout设置、状态码/异常类型判断重试逻辑，检查content-type再解析json，并记录脱敏的完整请求响应上下文用于排查。
requests 请求失败时怎么统一捕获异常
Python 里用 requests 调用 API，最常见的是网络抖动、超时、服务端返回非 2xx 状态码这三类问题。它们不能全靠 try/except Exception 一锅端——比如 requests.exceptions.Timeout 和 requests.exceptions.ConnectionError 需要重试，而 401 Unauthorized 就该立刻停手换 token。
- 必须显式捕获
requests.exceptions.RequestException（它是所有 requests 异常的基类），而不是裸写except: -
response.raise_for_status()只处理 4xx/5xx，不处理网络层错误，得和try/except配合用 - 超时一定要设
timeout=(3, 7)（连接 3 秒 + 读取 7 秒），否则卡死在 DNS 解析或空响应上很常见
如何区分该重试还是该放弃
不是所有失败都值得重试。比如 400 Bad Request 是你参数错了，重试十次也没用；但 503 Service Unavailable 或 ConnectionError 就适合加退避重试。
- 重试场景：状态码在
[429, 500, 502, 503, 504]中，或异常类型是ConnectionError/Timeout/TooManyRedirects - 放弃场景：
401（token 过期）、403（权限不足）、404（路径错）、422（参数校验失败） - 用
tenacity库比手写 while 循环更稳，它支持 jitter 退避和按异常类型过滤重试条件
response.json() 报 JSONDecodeError 怎么办
API 返回空体、HTML 错误页、或者 Content-Type 不是 application/json 时，response.json() 必然炸。这不是你代码写错了，是没做内容健壮性检查。
- 永远先检查
response.status_code和response.headers.get("content-type")，再决定是否调.json() - 别直接
response.json()，改用response.json() if "json" in response.headers.get("content-type", "") else None - 如果必须解析，包一层
try/except json.JSONDecodeError，并把response.text[:200]打出来——很多时候你看到的是 Nginx 502 页面或 Django debug 页面
日志里怎么记录失败请求才方便排查
只记 “API 调用失败” 没用。线上出问题时，你要能靠日志还原出完整上下文：发了什么、收到什么、在哪卡住。
立即学习“Python免费学习笔记（深入）”；
- 必须记录：
url、method、status_code、elapsed.total_seconds()、response.headers.get("content-type") - 敏感字段如
Authorization头、password参数要脱敏，但保留字段名和长度（例如"Authorization": "Bearer *** (len=42)"） - 不要在日志里 dump 整个
response.text，大响应体可能撑爆日志系统；用response.text[:500]+ 标注是否被截断
真正麻烦的是跨服务链路里 token 刷新、重定向跳转、gzip 响应解压失败这些隐性环节——它们不会报错，但会让 response 内容和预期对不上。每次加新 API，先抓包看原始 HTTP 流，比对着文档瞎猜强得多。
