中转 API 常见 429/502/530 状态码速查表（附自检命令）

图 1：三次探测后的分流——「该等」与「该查」的处理路径（示意图）

先跑一遍「三次探测」拿到判断依据

在做任何处理之前，先用这条命令连打三次，把状态码和耗时记录下来——后面每个判断都基于它：

for i in 1 2 3; do \
  curl -sS -o /dev/null -w "第${i}次: %{http_code}  耗时%{time_total}s\\n" \
  -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":8,"messages":[{"role":"user","content":"hi"}]}' \
  --max-time 30; sleep 20; done

三次全过=问题已自愈；时好时坏=限流类；三次全挂且状态码一致=链路类，按下面各节对症。

429 · Too Many Requests —— 限流与额度

一句话定性：服务方明确告诉你「太快了」或「没额度了」，请求本身没问题。责任方：多数在调用侧。

典型触发：脚本并发开太高；短时间重试风暴（失败后无间隔狂点重试是最常见的自我放大）；账户余额/额度池耗尽。

立即动作：

1. 看响应头里的 Retry-After（有值就按它等），没有就用指数退避：等 30 秒 → 1 分钟 → 2 分钟。
2. 检查自己的并发数：客户端多开、脚本线程数、多设备共用同一 Key。
3. 反复 429 且与频率无关 → 多半是额度问题，按 insufficient_quota 决策树核对余额与额度池。

自检命令——把响应头完整打出来，限流信息通常都在里面：

curl -sS -D - -o /dev/null -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":8,"messages":[{"role":"user","content":"hi"}]}' | grep -iE "HTTP/|retry|ratelimit|rate-limit"

该等别查：429 是确定性信号，任何「换网络 / 重装客户端 / 改 Base URL」都不会改善它。持续超过 10 分钟的全 429 才升级为服务方问题（限流阈值调整），带时间线和 Key 前缀去售后群问。

502 · Bad Gateway —— 中转网关的上游断了

一句话定性：中转网关本身活着，但它背后的上游服务给它回了无效响应或直接断连。责任方：服务端。

典型触发：上游模型服务抖动；中转节点重启或部署中；上游连接池打满。

立即动作：

1. 停手等 1-5 分钟——上游抖动大多自愈，连续重试只会让你的日志更难看。
2. 用「三次探测」确认是稳定复现还是偶发。
3. 稳定复现超过 10 分钟 → 查服务方状态页 / 售后群公告，大概率不止你一个人挂。

自检命令——看错误是稳定出现还是偶发，同时记录耗时给售后反馈用：

curl -sS -o /dev/null -w "code=%{http_code} 连接=%{time_connect}s 总耗时=%{time_total}s\\n" \
  -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":8,"messages":[{"role":"user","content":"hi"}]}' --max-time 30

反馈模板：向服务方报障时带上「时间点 + 三次探测的状态码与耗时 + 使用的 Base URL 形态」，一轮就能定位，比「我挂了」省两个来回。

530 —— 边缘到源站中断（Cloudflare 系）

一句话定性：530 不是标准 HTTP 状态码，是 Cloudflare 系边缘网络「连不上你源站」时的专用码。责任方：服务端的源站或 DNS。

典型触发：源站宕机或重启中；源站防火墙把边缘节点 IP 拒了；DNS 记录指错。

立即动作：

1. 先用浏览器打开服务方主站：主站也挂 = 整站故障，等公告即可。
2. 主站正常、只有 API 挂 → 可能是 API 源站单独故障，走售后反馈。
3. 如果你自己在服务方平台配置过自定义域名/回源，优先检查 DNS 与防火墙（源站只允许边缘 IP 段回源是这类架构的常见坑）。

自检命令——直接对比主站与 API 端点的可用性：

curl -sS -o /dev/null -w "主站: %{http_code}\\n" https://服务方主站域名/
curl -sS -o /dev/null -w "API:  %{http_code}\\n" "$ANTHROPIC_BASE_URL/v1/models"

本文不展开 530 背后的 1016/1033 等子码——那属于服务方运维域，用户侧能做的判断到「整站挂 vs 单 API 挂」就足够了。

相邻状态码速查行

顺手把容易混淆的邻居们放在一张小表里：

相关问题

401 / 404 / Invalid API key 这类「确定性错误」的对照处理，见 Claude Code 连不上 API：6 个报错串对照排查；Base URL 与 Provider 的配置核对方法，见主站的 Codex API 配置自检。

维护说明

本文按 2026-09 的通用 HTTP 语义与中转服务常见行为整理；429/5xx 的具体限流阈值、Retry-After 行为与 530 子码细节以服务方与 CDN 官方文档为准，客户端或服务架构大版本变更后会复测并更新日期。