4.2 常见错误码字典与排错指南

本节目标：汇总大模型 API 调用中最常见的 HTTP 状态码、错误信息及对应解决策略，告别盲目猜疑。

大模型 API 的请求与响应遵循标准 HTTP 协议。如果请求没有顺利得到回复，网关或上游模型会返回对应的 HTTP 状态码。

错误码全景速查表

状态码	英文提示	核心根因	解决对策
`401`	`Unauthorized / Invalid API Key`	API Key 错误、多复制了空格或 Key 已被禁用	重新核对并复制控制台中的 `sk-xxx` 凭据
`403`	`Insufficient Quota / Forbidden`	账户余额不足，或所选模型不在当前 Key 业务组	前往控制台充值，或在 Key 设置中勾选全部分组
`429`	`Too Many Requests / Rate Limit`	达到每分钟并发 (RPM/TPM) 限制或请求频次过高	降低并发任务数，或在客户端中配置适当的退避重试
`502` / `503`	`Bad Gateway / Service Unavailable`	上游原厂服务突发抖动，或上游算力节点维护	切换至官方主线路，或稍等 1~2 分钟重试
无报错卡死	首字长时间等待 (TTFT > 60s)	客户端一次性发送了 100k~160k 超长上下文	这是大模型 Prefill 预处理正常计算耗时，非卡死

常见原因：
1. 填入的 Key 前后带有看不见的空格或换行符；
2. 环境变量未生效（例如修改了 ~/.zshrc 但没有执行 source，或者终端未重启）；
3. 控制台中该 Key 被手动点击了「禁用」或被设置了过期时间已过期。
排查方法：运行 4.1 自检命令与探活，若终端同样报 401，立即去控制台生成一条全新 Key。

常见原因：
1. 账户余额已耗尽（或者欠费进入负值）；
2. 该 Key 单独设置了「额度上限」，且已消耗完毕；
3. 您所调用的模型属于专属高级号池，而当前创建的 Key 未勾选该业务分组（例如调用 claude-3-7-sonnet 但 Key 没勾选 kiro 或 ccmax）。
排查方法：登录控制台「钱包」查看当前可用余额；检查「令牌」管理中该 Key 的已用额度是否撞顶，或重新勾选所有 6 大可用业务分组。

常见原因：
1. 在 Cursor Composer 或自动化 Agent 脚本中，并发开启了过多并行的代码文件修改；
2. 使用了超低价特惠分组（如 国模特惠0.05x，系统强制限制单并发与每分钟 5 次请求）。
排查方法：减少同时打开的多会话 Agent 数量，或在令牌设置中将业务分组切换为 国模0.25x 主力商业组。

很多开发者在使用 Cursor、Codex 或 Claude Code 分析一个拥有数万行代码的项目时，常常反馈：“发送了指令后一直转圈没反应，等了一分钟是不是网关死机了？”

深度原理解密：长上下文首字延迟 (Prefill)

当您让 AI 阅读大型工程时，客户端可能会一次性打包 100k ~ 160k Tokens 发送给模型；
哪怕是官方原厂的顶尖集群，处理 150k Tokens 的注意力矩阵预计算（Prefill 阶段），天然就需要 40 ~ 90 秒 才能吐出第 1 个字符；
一旦首字吐出，后续输出速度会恢复到每秒几十字的高速打字状态；
这不是系统卡死，请耐心等待 1~2 分钟，切忌中途连续狂点停止与重试，以免产生重复扣费。

常见原因：全球大模型官方（如 OpenAI、Anthropic 等）遭遇突发宕机、机房电力波动或内存保护机制。
排查方法：
1. 将 Base URL 从国内专线 https://hk.azy6.cc/v1 切换为官方主线 https://azy6.cc/v1；
2. 换用同一级别的替代模型（如 claude-3-7-sonnet 短暂不可用时，先用 deepseek-chat 或 gpt-4o 临时顶替）。

下一步：查看全站常见问题与资深答疑 → 第五章 FAQ