先说句实话：我现在看到项目里直接裸调 API 就怕。接口调用失败这件事，大多数时候问题不是出在提供方，而是调用方基础逻辑太糙——超时不设、状态码不看、失败后就地崩溃。后来我也踩够了，干脆封装了一个带重试、退避、熔断和流式收尾的 API 调用函数。这套代码目前在部门里被多个脚本和后台任务用着，最直观的变化是：以前半夜报警“调用失败”，现在只剩真·业务异常才会打扰人。
这篇文章不是讲高大上架构，就是给你一个能直接复制回来改的“打不垮”版本。适合三类人看：写爬虫和脚本的、接大模型接口做工具的、还有批量调度任务里整天被偶发 502 折磨的后端。
1. 先想明白：什么样的错误值得重试，什么样的错误重试也没用
写封装之前最忌讳一上来就while True+try except，那样不是打不垮，是把自己做成一台无脑撞墙机器。先说一个核心判断：不是所有异常都应该被处理，很多异常重试 100 次结果一模一样，纯粹浪费请求和时间。
我习惯把失败先分成四类来看。
1.1 网络层异常：连接拒绝、DNS解析失败、连接中断
这类问题通常是瞬时的，比如对方服务的网关刚好在发布、机房网络抖动、本机 DNS 缓存暂时抽风。对于这种情况，隔几百毫秒到几秒再试一次，成功率往往会明显回升。
requests 里面的典型表现是：
ConnectionError：建立连接阶段就失败Timeout：连接超时或读取超时ChunkedEncodingError：响应头收到了，但 body 读到一半连接被掐
它们的特点是：请求可能根本没到达服务端，或者服务端还没开始处理，所以重试的代价比较低。
1.2 HTTP 状态码中的“暂时性错误”：408、425、429、500、502、503、504
这里要特别强调 429。很多API会做限流，一旦超过阈值就返回 429，聪明一点的响应里还会带Retry-After头告诉你“过几秒再试”。如果业务侧完全不理会 429，只是一味重试，那你不仅得不到数据，还会被封得更狠。
5xx 一类的状态码，比如 500、502、503、504，大概率是服务端自己出了问题或者负载过高，这时候重试通常是合理的。但注意，重试频率和总次数一定要控制，否则就是给已经脆弱的服务继续施加压力。
1.3 请求本身错误：400、401、403、404、409、422
这类状态码代表的是请求参数、鉴权、权限、资源状态出了问题。比如模型 ID 传错了、API Key 过期了、参数格式不合法、某个资源已经被删除。这种错误无论重试多少次都一样，属于永远不可能成功的请求。
我在代码里专门做了一个NonRetryableError，遇到这类就直接抛出，让上层业务立即知道，而不是糊里糊涂地重试 N 次以后才放弃。真实项目里最怕的就是：下游本来想让你知道“你的 key 欠费了”，你这边还傻傻重试半小时，白白浪费时间和金钱。
1.4 内容层错误：返回 200 但解析失败或业务码失败
这一层容易被忽视。有些老接口无论逻辑多错都返回 HTTP 200，只是 body 里带一个code: 5001，如果你只看 HTTP 状态码，很容易误判为成功。
处理方式是把“业务失败码”也纳入决策。比如某些大模型接口在服务端超时后，会返回带code的错误 JSON；某些文件处理接口返回"status": "failed"。在call_api函数外面，建议加一个回调或者约定一个is_business_error函数，把这类情况也映射成可重试或不可重试。
先列一个表方便随时翻：
| 失败类型 | 典型例子 | 是否应该重试 | 原因 |
|---|---|---|---|
| 网络层失败 | DNS错误、连接拒绝、连接中断 | 是 | 大多是瞬时问题 |
| 请求超时 | 连接超时、读超时 | 视幂等性而定 | 可能服务端已处理，重试会造成重复 |
| 限流 | HTTP 429 | 是，但要遵守 Retry-After | 等限流窗口过去 |
| 服务端问题 | 500、502、503、504 | 是 | 暂时性故障概率大 |
| 参数/权限错误 | 400、401、403、404 | 否 | 请求本身不可能成功 |
| 内容解析失败 | 200 但 JSON 解析失败 | 可先重试一次 | 可能响应不完整或网关给了一段 HTML |
| 业务错误码 | code: 10001 余额不足 | 否 | 等了也不会自动解决 |
1.5 幂等性这个前提，必须摆在桌面上
还有一个前置问题：如果重试，第二次请求会不会产生副作用？
比如调用支付接口、创建订单、上传文件，如果你只是简单地把原始请求重发一遍，很可能造成重复扣款、重复下单。对这种场景，不能把“自动重试”做成默认选项，要么让调用方显式声明idempotent=True，要么在请求头里传幂等键（常见的如Idempotency-Key: request-uid-xxx）。
判断标准很简单：这个请求发出后，哪怕服务端已经成功处理，只是因为响应丢了，我再补发一次，会不会出事？如果不会，那就可以放心自动重试；如果会，那就必须引入幂等键，否则你所谓的“打不垮”，是在替项目制造更大的麻烦。
2. 单纯多试几次不够：退避、抖动和熔断才是关键
把“什么时候该重试”想清楚以后，接下来才是重试策略本身。这里最容易犯的错是固定延时循环，比如每次失败等 1 秒再试。固定延时在小规模请求下没毛病，但一旦同时有几十个任务都失败，它们的重试节奏会完全同步，造成“惊群效应”：每 1 秒大家一起打一次接口，很容易再次触发服务端限流或雪崩。
2.1 指数退避为什么要存在
指数退避是业界最基础的做法：第一次失败后等 1 秒，第二次失败后等 2 秒，第三次等 4 秒，第四次等 8 秒。给服务端更多恢复时间，也让自己的重试不要那么密集。
公式大概是：
delay = min(base_delay * 2 ** (attempt - 1), max_delay)其中attempt是从第 1 次失败开始计数，也就是第 1 次失败后等base_delay，第 2 次失败后等2 * base_delay。max_delay是上限，防止退避时间无限变大。
2.2 抖动到底是什么，又是干嘛用的
指数退避还远远不够。假设 base_delay = 1 秒，有 30 个线程同时碰上了服务端抖动，第一次失败后它们可能都在第 1 秒左右重试，等于把刚刚还脆弱的上游又打了 30 次。
解决方式是在退避时间基础上加一个随机值，叫“抖动（jitter）”。最常见的做法是：
delay = min(base_delay * 2 ** (attempt - 1), max_delay) delay = delay + random.uniform(0, jitter_ratio * delay)jitter_ratio取 0.2 到 0.5 之间比较常用。加了这个随机量以后，同样失败的 N 个请求不会在同一点齐刷刷地发起重试，而是自然地分散开。
2.3 熔断：不是每个函数都要，但高并发场景必须有
“打不垮”不代表“永远在打”。如果你的服务正在经历大面积超时，下游已经明显过载，此时所有调用方如果依然按照重试策略拼命重试，只会让故障雪上加霜。这种时候需要的是熔断：连续失败次数达到阈值后，直接快速失败，不再发起新请求；等过一段时间，再放少量试探请求，确认下游恢复后再逐渐放开。
给一个简单比喻：一个人已经生病了，你一遍遍按门铃问“你好点了吗”，他只会更难受。最好的办法是让他安静休息半小时，半小时后再去敲门问一次，能开门就说明恢复了。
熔断状态一般有三种：
- closed：正常放行请求
- open：熔断打开，直接拒绝，不再请求下游
- half_open：熔断恢复前的试探阶段，允许少量请求通过
至于“连续失败多久算故障”，每家服务不一样。普通的内部API我一般设连续失败 5 次触发熔断，熔断恢复时间是 30 秒；大模型接口这种单次调用成本高的，熔断条件更严格一点，但恢复时间可以保持在 30 到 60 秒。
3. 完整代码：先把一个普通 JSON 接口的调用函数做扎实
下面这个函数面向的是绝大多数普通 API 场景：POST 或 GET 发出去，返回 JSON。它包含指数退避、随机抖动、超时控制、有限重试、状态码分流、熔断开关和重试回调。直接复制到一个api_guard.py文件里就能用。
3.1 公共配置与断路器
import random import threading import time from dataclasses import dataclass from typing import Optional import requests DEFAULT_RETRIABLE_STATUS = frozenset({408, 425, 429, 500, 502, 503, 504}) @dataclass(frozen=True) class RetryPolicy: max_attempts: int = 4 base_delay: float = 1.0 max_delay: float = 30.0 jitter: float = 0.3 timeout: Optional[tuple] = None retriable_status: frozenset = DEFAULT_RETRIABLE_STATUS retry_on_timeout: bool = True retry_on_connection_error: bool = True total_timeout: float = 300.0 class CircuitOpenError(RuntimeError): pass class RetryableHTTPError(RuntimeError): def __init__(self, status_code: int, text_snippet: str = ""): super().__init__(f"HTTP {status_code}: {text_snippet[:200]}") self.status_code = status_code self.text_snippet = text_snippet[:200] class NonRetryableError(RuntimeError): pass class RetryExhausted(RuntimeError): pass
