HTTP 状态码只告诉你"请求有没有到达服务器"，不告诉你"业务操作有没有成功"。把 200 当成功是接口开发里最常见的误判。
一、两层状态码——传输层和业务层
HTTP 200 表示服务器收到了请求并返回了响应。但响应体里的业务状态码可能是失败：参数错误（如 1001）、Token 失效（1002）、限频（1004）、账号掉线（1005）。HTTP 层面完全正常，业务层面已经失败。
反过来，HTTP 500 可能是服务器临时错误，重试后成功——传输层失败不代表业务最终失败。两层要分开判断。
二、业务码的分类处理
成功码：通常是固定值（如"1000"），拿到成功码才继续后续逻辑。参数错误：不重试，检查参数——重试同样错误的参数没有意义。鉴权失效：不重试，触发 Token 刷新或告警——这个错误不修复，后续所有请求都会失败。限频错误：等待后重试，间隔按文档要求（通常30秒以上）。状态异常（掉线）：不重试，触发重连流程，恢复后重发。
每类错误的处理策略完全不同，统一"失败就重试"会把参数错误也重试，浪费配额还刷错误日志。
三、响应体的数据完整性检查
业务码成功不代表返回数据完整。比如发消息接口返回成功但 data 里没有 msgId——消息可能发出去了但拿不到撤回标识。查询接口返回成功但 data.list 为空——可能是真的没数据，也可能是分页参数错了。
关键业务操作要检查返回数据的关键字段：发送后检查 msgId 是否存在，查询后检查列表字段是否存在。数据缺失按异常处理。
错误码处理对照
业务码类型 | 典型含义 | 处理策略 | 重试？ |
|---|---|---|---|
成功 | 操作完成 | 检查data完整性 | 否 |
参数错误 | 参数缺失/格式错 | 修参数 | 否 |
鉴权失效 | Token过期 | 刷新/告警 | 刷新后重试 |
限频 | 调用过密 | 等待30秒+ | 是 |
掉线 | 实例离线 | 触发重连 | 恢复后重试 |
两层判断实现
class APIResponse: """统一响应解析""" SUCCESS = "1000" def __init__(self, http_status, body): self.http_ok = 200 <= http_status < 300 self.code = str(body.get("code", "")) self.msg = body.get("msg", "") self.data = body.get("data") @property def is_success(self): return self.http_ok and self.code == self.SUCCESS def handle_error(self, method, params): if self.code == "1001": raise ParamError(f"{method} 参数错误: {self.msg}") if self.code == "1002": refresh_token() # 刷新后由调用方决定重试 raise AuthError("Token已刷新，请重试") if self.code == "1004": raise RateLimitError("等待30秒后重试") if self.code == "1005": trigger_reconnect() raise OfflineError("账号掉线，重连中") raise APIError(self.code, self.msg) def safe_call(method, params, max_retry=2): """带分类重试的安全调用""" for attempt in range(max_retry + 1): resp = raw_http_call(method, params) r = APIResponse(resp.status, resp.json()) if r.is_success: # 数据完整性检查 if method == "sendText" and not r.data.get("msgId"): raise DataIncomplete("发送成功但无msgId") return r.data # 分类处理 try: r.handle_error(method, params) except RateLimitError: time.sleep(30); continue except (ParamError, AuthError, OfflineError): raise # 不重试 raise MaxRetryExceeded(f"{method} 重试{max_retry}次仍失败")落地建议
两层判断是接口调用的基本功：HTTP 状态码管传输，业务码管逻辑，缺一不可。错误处理按码分类——参数错误不重试、限频等待重试、鉴权失效先刷新、掉线先重连。成功响应也要检查关键字段完整性。业务码清单和含义以 Eyun 开发文档 为准。
