X API 错误码:哪些该重试,哪些该停下
X API 错误码:哪些该重试,哪些该停下
API 的错误处理大多数人都会写两遍。第一版捕获一切然后重试。第二版是在那玩意儿一夜之间重试了一万一千次 402 之后写的。
有用的区分不是「错误 vs 成功」,而是★同一个请求过一会儿会成功吗?★ 三个码说会、几个码说永远不会,还有一个说「除非你那边改点东西」。把这几组分对,错误处理就完成了大半。
有个免费 demo 端点,写 handler 时可以用它触发真实响应,不用猜结构。
错误信封
失败以统一结构返回——下面是写这篇时实拉的真实响应:
{
"status": "error",
"error": { "code": 401, "message": "invalid or revoked API key" },
"request_id": "req_1794064042133_12236",
"credits_used": null
}
★失败时 credits_used: null 是值得注意的那部分。★ 失败的请求没有计费,这改变了重试的经济学:429 之后重试只花时间,不花钱。
★把 request_id 记进日志。★ 它是唯一能让人把你的失败和服务端记录对应起来的东西。以 request ID 开头的技术支持对话能得到答案;以「它昨天一直在失败」开头的通常得不到。
决策表
| 码 | 含义 | 重试? | 怎么做 |
|---|---|---|---|
| 429 | 被限流 | 是 | 退避后重试。不计费。 |
| 502 / 503 | 上游或服务不可用 | 是 | 指数退避,次数要有上限 |
| 500 | 服务端错误 | 一到两次 | 持续出现就不是暂时性的 |
| 402 | 额度用尽 | 绝不 | 告警找人。同一请求会同样失败。 |
| 401 | key 无效或被吊销 | 绝不 | 修 key。重试不可能有用。 |
| 403 | 禁止访问 | 绝不 | 你在要一个不被允许的东西 |
| 404 | 不存在 | 绝不 | 账号或帖子不存在,或者受保护 |
| 400 / 422 | 请求有误 | 绝不 | 参数错了——改调用 |
★真正要紧的那条线在 429/5xx 和其他一切之间。★ 线以上,等待会改变结果。线以下,请求是确定性的——重试是一个烧时间的循环。
RETRYABLE = {429, 500, 502, 503, 504}
def should_retry(status: int, attempt: int, max_attempts: int = 3) -> bool:
if status not in RETRYABLE:
return False # 确定性失败 —— 停下
return attempt < max_attempts
整个策略就这些。其余都是退避算术。
404 是大家最容易搞错的那个
用户查询返回 404 至少有四种不同原因,而它们需要不同的反应:
| 原因 | 怎么判断 | 怎么做 |
|---|---|---|
| 这个用户名从不存在 | 永久 | 标记无效,别再问了 |
| 账号改名了 | 那个 ID 现在挂在另一个用户名上 | 按用户 ID 重新解析,不要按用户名 |
| 账号被封 | 之前能用,现在 404 | 记下日期,保住已有数据 |
| 账号受保护 | 公开存在,但读不到 | 标记,不要重试 |
★用户名是可变的,用户 ID 不是。★ 如果你在长期追踪账号,把数字 ID 当主键,把用户名当展示属性——和入库时该用 ID 做主键是同一个道理。否则改名的账号会从你的采集里悄悄消失,看起来像被删号了。
★绝不要按定时计划重试 404。★ 唯一站得住的模式是慢速复查——按周,不是按分钟,因为封号偶尔会被撤销。对一个不存在的账号做分钟级重试,就是人们怎么把整个配额花在虚无上的。
429 其实是三件不同的事
这是最值得理解的那个失败,因为正确的等待时长因成因而异:
- 每秒突发——你一次并发打了一百个请求。靠限制并发解决,不是靠等更久。
- 窗口配额——当前窗口的额度用完了。靠等窗口滚过去解决。
- 上游压力——服务商在自己的源头上限流。只能靠等;你的并发不是问题所在。
它们返回同一个状态码,所以你没法从单次响应里区分。但你可以用一种对三者都正确的方式反应:★指数退避、给延迟设上限、并且独立地限制并发。★ 完整拆解在「rate limit exceeded」到底指什么。
import random, time
def backoff_delay(attempt: int, base: float = 1.0, cap: float = 60.0) -> float:
"""指数退避 + 全抖动, 带上限。"""
raw = min(cap, base * (2 ** attempt))
return random.uniform(0, raw)
★那个抖动不是装饰。★ 没有它,撞上同一个限流的每个 worker 都会在同一瞬间重试,于是你的集群自己同步成一波惊群、再次触发限流。把延迟随机化就能把重试摊开,而这只要一行。
鉴权在路由之前
一个很小但很容易让人困惑的行为,已对线上实测:请求一个不存在的路由,在没有有效 key 的情况下返回 401,不是 404。
$ curl -s "https://api.socialapi.tech/v1/does/not/exist"
{"status":"error","error":{"code":401,"message":"invalid or revoked API key"},...}
对在边缘做鉴权的 API 来说这很正常,而它对排查很要紧:★如果你在一个自认为已鉴权的调用上拿到 401,先检查 URL,再去重新生成 key。★ 路径打错和 key 失效产生同一个响应,而人们通常先怀疑 key。
超时不是错误,是未知
超时是唯一一种你真的不知道发生了什么的情况。请求可能被处理了,也可能没有。
对读操作这无所谓——随便重试,取两遍没有害处。但当请求有副作用时就有所谓了,而对只读 API 来说,那主要指你自己的记账:
def fetch_with_state(api, target, state):
try:
rows = api.fetch(target)
except TimeoutError:
# 不要推进游标 —— 我们不知道那一页到底拿到没有
state.mark(target, "unknown")
return None
state.advance(target, rows)
return rows
★规则:在歧义性失败上,不要推进状态。★ 重读一页只花一个请求。跳过一页会静默丢数据,而你永远不会知道它缺了——和限流之后不要推进高水位是同一个道理。
一个值得抄的 handler
import requests, time, random
RETRYABLE = {429, 500, 502, 503, 504}
class Permanent(Exception): pass
class OutOfCredits(Permanent): pass
def call(url, params, headers, max_attempts=4, timeout=30):
last = None
for attempt in range(max_attempts):
try:
r = requests.get(url, params=params, headers=headers, timeout=timeout)
except requests.Timeout:
last = "timeout" # 未知: 重试, 但不要推进状态
time.sleep(random.uniform(0, min(60, 2 ** attempt)))
continue
except requests.RequestException as e:
raise Permanent(f"network: {e}") # DNS、TLS —— 不值得盲目重试
if r.status_code == 200:
return r.json()
body = {}
try:
body = r.json()
except ValueError:
pass
err = (body.get("error") or {})
rid = body.get("request_id", "?")
if r.status_code == 402:
raise OutOfCredits(f"{err.get('message')} [{rid}]")
if r.status_code not in RETRYABLE:
raise Permanent(f"{r.status_code} {err.get('message')} [{rid}]")
# 可重试: 有 Retry-After 就听它的
wait = r.headers.get("Retry-After")
delay = float(wait) if wait and wait.isdigit() \
else random.uniform(0, min(60, 2 ** attempt))
last = f"{r.status_code} [{rid}]"
time.sleep(delay)
raise Permanent(f"gave up after {max_attempts}: {last}")
这里有三个选择是刻意的。
★OutOfCredits 是独立的异常类型。★ 它需要和其他所有失败都不同的反应——必须有人去处理——所以它不该被那个「记个日志然后继续」的 handler 捕获。
有 Retry-After 就听它的。 服务端告诉你该等多久的时候,猜不如听。
网络异常直接抛、不重试。 DNS 或 TLS 失败通常是配置问题,重试四次只是延迟你发现这件事。
我们的 API 在每次失败上都返回上面那个信封,成功和错误都带 request_id。用 Google 一键注册送 $0.20 额度、不用信用卡,够你刻意触发上面每一个码、确认你的 handler 对每一个都做对了事。
常见问题
X API 的 429 是什么意思? 你被限流了。这个请求没有计费,而且同一个请求过一会儿会成功——该退避重试,不该当成失败。
被限流的请求会计费吗?
不会。 失败响应带 credits_used: null,这就是为什么重试 429 花时间但不花钱。
402 有任何该重试的情况吗? 没有。 它意味着你额度用光了,而且在有人充值之前会一直这么意味着。给它单独的异常类型,让人收到告警。
什么会导致 401? key 缺失、格式错误或被吊销——或者 URL 不存在,因为鉴权在路由之前。重新生成 key 之前先检查路径。
URL 写错为什么返回 401 而不是 404? 因为鉴权发生在边缘、在路由匹配之前。路径打错和 key 无效产生同一个响应,这是常见的排查陷阱。
401 和 403 有什么区别? 401 是「我们不知道你是谁」;403 是「我们知道,但你没权限」。两个都不是靠重试解决的。
用户查询的 404 意味着什么? 四种之一:这个用户名从没存在过、账号改名了、被封了、或者受保护。它们需要不同处理,不要合并。
账号改名了怎么处理? ★用数字用户 ID 做主键,不要用用户名。★ ID 不可变、用户名可变,所以按用户名存的记录会在改名时悄悄消失。
404 该重试吗? 不要按定时计划重试。 慢速复查——按周——是站得住的,因为封号有时会被撤销。对不存在的账号做分钟级重试是在浪费配额。
怎么区分封号和删号? 往往光从响应里分不出来。 记下 404 第一次出现的时间、保住你已经采到的数据——那个转变日期通常才是有信息量的部分。
哪些状态码值得重试? 429、500、502、503、504。 其他都是确定性的——同一个请求会同样失败。
重试几次合理? 三到四次,配指数退避。 到那时还没成功就大概不是暂时性的,而更多尝试只会延迟告警。
该用什么退避?
指数退避 + 全抖动 + 上限,大致是 random.uniform(0, min(60, 2**attempt))。
抖动为什么要紧? 因为没有它,撞上同一限流的每个 worker 会同时重试。你自己的集群会同步成一波惊群、再次触发限流。
该听 Retry-After 头吗? 有的时候该听。 服务端比你的退避公式更清楚;只在这个头缺失时才回退到公式。
超时该怎么处理? 当成未知,不是错误。 读操作可以重试,但不要推进任何游标或高水位——你不知道那一页到底送达没有。
超时之后为什么不能推进状态? 因为重读一页只花一个请求,而跳过一页会静默丢数据,并且你永远不会发现它缺了。
连接错误该重试吗? 通常不要盲目重试。 DNS 和 TLS 失败一般是配置问题,重试四次只是推迟你发现它。
失败时该记什么日志?
状态码、错误信息、以及 request_id。 request ID 是唯一能让人在服务端追踪你这次失败的字段。
request_id 是干什么的? 把你客户端的失败和服务端的记录对应起来。 带着它来问技术支持能得到具体答案。
400 通常意味着什么? 参数格式有问题——limit 不对、cursor 错了、必填字段缺失。不要重试,改调用。
三种 429 怎么区分? 从单次响应里区分不了。 改为用一种对三者都正确的方式反应:指数退避加抖动,外加限制并发,这样突发那一种就不是你自己造成的。
限流处理该放在客户端还是任务里? ★客户端★,这样每次调用都有。放在任务层意味着每个新调用点都要重新发明一遍,而其中总有一个会写错。
500 和 502 有什么区别? 500 是服务内部出错;502 是上游依赖失败。两个都值得重试,但持续的 500 更可能需要上报。
错误会算进我的限流额度吗? 被限流的响应不计费,但它确实说明你已经碰到边界了。解法是放慢节奏,不是增加重试量。
最该避免的那个错误处理错误是什么? ★把所有失败都当成可重试的。 一个 402 进了重试循环,能消耗掉整晚的运行时间而什么都不改变。★
429/5xx 和其他一切之间那条线,是你真正必须分对的唯一区别;其余都是退避算术。用 Google 注册送 $0.20 额度、不绑卡,可以拿线上端点把每个码都触发一遍。