错误码怎么读
先用状态码定位大类，再读错误体里的具体原因：4xx 基本是请求侧问题，重试无用；429 是限流，需要退避；5xx 多为服务端临时故障，适合带退避重试。把这三类分流做对，排障时间能省掉大半。错误体通常包含错误类型与描述，程序里应该记录类型字段而不是只记状态码。
基本信息
| 4xx | 请求或鉴权问题，重试通常无效 |
|---|---|
| 429 | 限流或额度耗尽，需退避后重试 |
| 5xx | 服务端异常，适合带退避重试 |
| 错误体 | 含错误类型与描述，应记录到日志 |
| 排查顺序 | 状态码、错误类型、请求体字段、模型名与版本 |
| 监控建议 | 按错误类型分别计数与告警 |
常见状态码速查
| 状态码 | 含义 | 常见原因 |
|---|---|---|
| 400 | 请求结构或参数错误 | 字段名写错、必填缺失、模式不合法 |
| 401 | 鉴权失败 | 密钥无效、头名写错、格式不对 |
| 403 | 无权限或区域限制 | 模型未开通、区域不可用、额度受限 |
| 404 | 路径或模型不存在 | 接口路径写错、模型名不被支持 |
| 413 | 请求体过大 | 上下文或图片超出上限 |
| 429 | 限流或配额耗尽 | 并发过高、超速率上限、余额不足 |
| 500 与 502 | 服务端异常或网关故障 | 上游抖动，重试常可恢复 |
| 503 | 服务暂不可用 | 维护或过载，退避后重试 |
典型使用场景
- 接入新平台：先跑通鉴权与一次最小请求排掉 4xx
- 线上排障：按状态码分层，快速判断是请求问题还是上游问题
- 重试策略：只对 429 与 5xx 重试，其余直接失败并告警
- 容量规划：统计 429 出现频率，判断是否需要提高配额或削峰
- 成本控制：余额不足类错误要提前告警，避免业务中断
分流处理的基本骨架
分流处理的基本骨架
def call_with_retry(fn, tries=4):
for i in range(tries):
try:
return fn()
except RateLimitError: # 429：按退避等待后重试
time.sleep(2 ** i + random.random())
except APIStatusError as e:
if e.status_code >= 500: # 5xx：服务端抖动，可重试
time.sleep(2 ** i)
else:
raise # 4xx：参数或鉴权问题，重试无意义
raise RuntimeError("重试次数用尽")同一个状态码在不同平台的含义可能略有差别：兼容端点与官方实现的错误类型划分不完全一致，接入时用真实错误各测一遍更可靠。
对 4xx 反复重试会把小问题放大成故障：一次请求变成多次，既消耗额度也可能触发限流，日志里还会出现大量重复报错。