PythonAPI错误统一处理技巧

本文深入探讨了Python中使用requests调用API时的异常统一处理最佳实践，强调必须显式捕获requests.exceptions.RequestException而非笼统的Exception，结合合理timeout设置、精细化的状态码与异常类型判断来区分重试（如503、ConnectionError）与立即终止（如401、403）场景，并推荐使用tenacity实现带退避和过滤的稳健重试；同时指出JSON解析前务必校验Content-Type和状态码，避免JSONDecodeError，并详述了如何记录脱敏但上下文完整的请求/响应日志（含URL、耗时、Header、截断响应体等），直击线上排查痛点，帮助开发者构建高可靠性、易调试、可维护的API调用层。

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 调用失败” 没用。线上出问题时，你要能靠日志还原出完整上下文：发了什么、收到什么、在哪卡住。

• 必须记录：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 流，比对着文档瞎猜强得多。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~