博客 / 排障指南

大模型 API 错误码速查：400 到 529 各代表什么、哪些该重试

2026-10-23cdnping 编辑部约 7 分钟读完

大模型 API 错误码可以先按一条线分开：4xx 基本是请求本身的问题，原样重试没有用，要改请求、换密钥或者等额度；5xx 和 524、529 多半是服务商或中间链路的问题，可以带退避重试。例外是 429：它是 4xx，但通常值得等一会儿再试，前提是先分清“速率超了”还是“余额没了”。

下面先给总表，再讲每一类该怎么确认，最后给一段重试逻辑的示例。各厂商对同一个状态码的细分不完全一样，表里写的是常见含义，具体以各家官方错误码文档为准。

#一张表：每个状态码是谁的问题、能不能重试

两个容易误判的点：

• 524 和 529 不是一回事。524 是 Cloudflare 的状态码，只说明“经过 Cloudflare 的那段链路等源站等超时了”，源站可能是官方 API，也可能是你自己或中转服务的服务器。529 是 Anthropic 文档里定义的过载码，出现时说明请求已经到了 Anthropic，是对方容量不足。
• 429 有两种。OpenAI 的 429 响应里，rate_limit_exceeded 是速率超限，等一下就好；insufficient_quota 是额度或账单问题，重试多少次都一样。Anthropic 的 429 是 rate_limit_error，响应头里带 retry-after。

#看到报错，先看哪三样东西？

状态码只是第一层信息。能定位问题的是下面三样，建议在日志里把它们和状态码一起记下来。

#1. 响应体里的错误类型

主流接口的错误响应都是 JSON，里面有一个类型字段：

• OpenAI 格式：error.type、error.code、error.message
• Anthropic 格式：顶层 type: "error"，error.type 是 invalid_request_error、authentication_error、permission_error、not_found_error、rate_limit_error、api_error、overloaded_error 这类值

同样是 400，error.message 可能写的是上下文超长，也可能是某个参数名拼错，处理方法完全不同。只记状态码不记 message，事后基本没法查。

#2. request_id

OpenAI 在响应头 x-request-id 里返回请求 ID，Anthropic 在响应头 request-id 里返回（响应体里通常也有）。找官方支持或者对比自己的服务端日志时，靠这个 ID 才能精确对上某一次请求。

#3. 响应是谁发出来的

502、504、524 这类码经常不是模型服务商发的，而是中间某一层：公司代理、反向代理、CDN、中转网关。判断方法：

# 只看响应头，确认是谁回的错误
curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{}'

上面故意发一个空请求体，正常应该收到 400 加上 request-id 头，说明网络链路通、请求确实到了官方。如果收到的是一个 HTML 页面、server: cloudflare 且没有任何请求 ID，或者是你代理软件自己的报错页，那问题在链路上，不在模型。OpenAI 也一样，可以对 https://api.openai.com/v1/models 发不带密钥的请求，预期是 401 加 x-request-id。

#4xx：怎么改请求，而不是盲目重试？

排查顺序可以这样走：

1. 401：检查环境变量是否真的被读到（echo ${#OPENAI_API_KEY} 看长度，不要把密钥打印出来）；检查请求头写法，OpenAI 格式用 Authorization: Bearer，Anthropic 格式用 x-api-key。用中转或自定义接口地址时，接口地址和密钥要配套，详细配置见Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置。
2. 404：多数是 base URL 少了或多了 /v1，或者模型名拼写不对。
3. 400 / 413 / 422：读 error.message。上下文超长就截断历史或换上下文更长的模型；参数问题对照文档逐个检查。
4. 403：可能是密钥权限不够，也可能是服务所在地区政策的限制。后者请按官方说明处理，遵守服务条款和当地法规，参见Claude 提示所在地区不受支持：原因、官方政策与合规选择。
5. 429：先区分类型。速率类按 retry-after 等待，并在客户端加并发上限；额度类去控制台看余额和用量限制。

4xx 一律不要进入自动重试循环。一个参数写错的 400 被重试 5 次，只会多 5 条一样的错误日志；OpenAI 的速率限制文档还说明，失败的请求同样计入每分钟限额。

#5xx、524、529：是不是全局故障？

服务端错误能重试，但先要回答：只有我这样，还是大家都这样？这决定了你是继续排查自己的链路，还是等官方恢复。

#三步判断

1. 看官方状态页和第三方监测。打开 cdnping 的 API 状态页，它从 Cloudflare 边缘每 5 分钟探测一次各家官方 API 入口，并每 15 分钟同步 OpenAI、Anthropic、Moonshot、Groq 等的官方状态页。如果是 Claude，直接看 /status/anthropic。状态页上的事件等级怎么理解，可以看怎么看 OpenAI 状态页和 Claude 状态页。
2. 看用户侧反馈。官方状态页通常比实际故障晚一些才更新。挂了吗页面综合了官方状态、每 5 分钟的 API 探测和用户一键报告（打不开、很慢、限流等），用户报告突然变多往往是更早的信号。
3. 从自己这边测一次。在在线测速里测一下目标 API 的首次连接和往返。连接本身就失败或者很慢，问题更可能在本地网络或代理；连接正常而请求返回 5xx，更可能在服务商。分层检查方法见ChatGPT 挂了吗？三步判断是服务故障还是自己的网络问题和Claude Code 连接超时和报错怎么排查。

#5xx 事件有多常见？

按 cdnping 从各家官方状态页同步的记录，2026-09-17 以来（截至 2026-10-17）：OpenAI 有 4 次 major、19 次 minor 级别的事件；Claude 有 6 次 major、1 次 minor；Moonshot 有 8 次 critical。同期 Cloudflare 状态页上也出现过 “Increased HTTP 502 Errors”“Increased HTTP 5xx Errors Ashburn” 这类事件，说明 502、5xx 有时来自 CDN 层，而不是模型服务商。按服务商的逐条梳理见AI 服务故障盘点：2026年9–10月。

一个月的窗口里就有这么多事件，客户端需要有重试和降级，不能假设上游一直可用。

#当前各 API 入口可达吗？

cdnping 在 2026-10-17 开始采集，下面是首批探测的结果（Cloudflare 边缘 DEN 节点，UTC 08:40–10:05，共 242 次探测，窗口很短，只能看个大概）：

这是从美国机房测的入口可达性，不代表你本地的体验，也不代表模型推理是否正常；它能回答的是“入口有没有整体不通”。探测口径见数据方法。

#重试逻辑怎么写？

把上面的表落到代码里，大致是这样。下面是 Python 示意，send() 和 resp 的属性是假设的接口，按你用的 HTTP 库或 SDK 改写：

import random, time

RETRYABLE = {500, 502, 503, 504, 524, 529}

def should_retry(status, body):
    if status in RETRYABLE:
        return True
    if status == 429:
        err = (body or {}).get("error", {})
        # 额度类 429 不重试
        return "insufficient_quota" not in (err.get("code"), err.get("type"))
    return False

def call_with_retry(send, max_attempts=5, base=1.0, cap=30.0):
    for attempt in range(max_attempts):
        resp = send()
        if resp.status < 400:
            return resp
        body = resp.json_or_none()
        if not should_retry(resp.status, body) or attempt == max_attempts - 1:
            rid = resp.headers.get("request-id") or resp.headers.get("x-request-id")
            raise RuntimeError(f"{resp.status} {rid} {body}")
        retry_after = resp.headers.get("retry-after")
        if retry_after and retry_after.isdigit():
            delay = float(retry_after)
        else:
            delay = min(cap, base * 2 ** attempt) * random.uniform(0.5, 1.0)
        if resp.status == 529:
            delay *= 2  # 过载时等久一点，减少对方压力
        time.sleep(delay)

实现时还要注意：

• 加随机抖动。多个进程同时失败、同时按固定间隔重试，会在同一时刻再打一波请求。
• 设总时长上限。交互式场景下用户等不了太久，重试 2–3 次失败就该提示或切到备用模型。
• 流式请求的重试要小心。已经输出了一半再失败，直接重发会重复内容，需要在应用层决定是续写还是重来。
• 504 和 524 反复出现时，先看请求本身。非流式请求生成很长的输出，很容易超过网关的等待时间，改成流式输出往往比重试更有效。
• 日志里记下状态码、错误类型、request_id 和耗时。想进一步统计自己的成功率，可以参考自己测 AI API 的可用率：指标、脚本与口径。

#用聚合网关时，错误码怎么归属？

经过网关或中转服务时，你看到的状态码可能是网关自己生成的，也可能是透传的上游错误。判断方法还是看响应体和请求 ID，网关一般会在错误里说明来源。

以 AGI Plan 为例（AGI Plan 是 cdnping 的商业合作方），它公开的可用率口径是“成功 /（成功 + 因平台自身原因失败）”，只有 5xx 计为平台失败，4xx 视为请求方的问题；逐小时数据可以在 https://agiplan.dev/api/status/requests?month=YYYY-MM 查到，不需要登录，cdnping 的 /status/agiplan 也有镜像。评估任何网关时，都可以问同样的问题：它怎么区分 4xx 和 5xx，可用率按什么口径算，数据能不能公开核对。更多检查项见AI API 中转站怎么选：可用率、计费、数据政策 8 项检查。

#排查检查表

遇到报错时按顺序过一遍：

• 记下状态码、error.type / error.code、error.message、request_id
• 4xx：按表改请求、查密钥、查余额，不要自动重试（速率类 429 除外）
• 确认响应来自官方还是中间层（看响应头和请求 ID）
• 5xx / 524 / 529：打开 /status 和 /down 看是否大面积故障
• 在在线测速测一次连接，排除本地网络
• 重试用指数退避加抖动，尊重 retry-after，设总时长上限
• 504 / 524 反复出现时，检查输出长度，考虑改流式