首页 / 指南 / 401 / 402 / 429 报错排查
401 / 402 / 429 报错排查
401 是鉴权问题（Key 无效、过期或没带对），402 是余额/付费状态问题，429 是限速——先分清撞的是分钟级还是日级限速：分钟级等一会儿再试，日级等到重置时间，不要无脑重试。
先看表：三个状态码分别改什么
| 状态码 | 通常含义 | 先查什么 |
|---|---|---|
| 401 | 鉴权失败：Key 无效、过期或没带对 | Key 是否复制完整、是否过期/被撤销、请求头格式、是否选错了项目/账号 |
| 402 | 余额/付费状态问题 | 控制台的余额与免费额度状态、是否需要绑卡或开通后付费 |
| 429 | 限速：撞上分钟级或日级上限 | 报错信息写的是哪种限速、Retry-After、重置时间 |
具体语义以各厂商文档为准；有的厂商会用 429 表示额度用完，有的用 402 表示需要付费。
401：鉴权失败
- Key 是否复制完整（首尾空格、换行都会导致失败）；
- Key 是否过期、被撤销、或属于另一个项目/账号；
- 请求头格式是否按厂商文档填写（不要凭记忆拼）；
- 是否把 Key 填到了错误的字段（例如把 Key 当成了模型名）。
402：余额 / 付费状态
先去控制台看余额与免费额度状态：是免费额度用完了，还是账户需要绑卡/开通后付费。有的厂商在免费额度用完后直接停用，有的转按量计费（见本站每条的「注意」事项）。不要反复重试，402 不是重试能解决的。
429：限速——先分清分钟级还是日级
限速有四个轴：RPM（每分钟请求数）、TPM（每分钟 Token 数）、RPD（每天请求数）、TPD（每天 Token 数）。四个轴同时生效，撞上任何一个都返回 429。本站额度原文的例子：Groq 是「每模型 30 RPM / 1,000 次每天 / 20 万 Token 每天」，OpenRouter 免费模型是「20 RPM / 50 次每天」，Gemini 免费层是「5–30 RPM / 按模型限日额」。
分钟级限速等一会儿再试；日级限速要等到重置时间。有的厂商会在响应头里给 Retry-After（建议等待秒数），以该值为准。注意：OpenRouter 的注意事项明确写明「失败请求也计入每日上限」，无脑重试会加速耗尽日额。
每天重置的额度：重置时间对照（照录本站数据）
| 额度 | 重置说明（照录） |
|---|---|
| API-Inference 每日免费额度（ModelScope 魔搭） | 每天重置，当日不用不结转 |
| 每日免费 Token（蚂蚁百灵 Ling Studio） | 每天 02:00 前发放，当日不结转 |
| 促销模型每日免费 Token（华为云码道 CodeArts） | 每天 24:00（UTC+8）重置，先到先得 |
| Token Factory 免费模型 API（AMD Radeon Cloud） | 北京时间 0 点重置，每日额度因账号而异 |
| K2-Horizon 每日免费额度（IFM） | UTC 0 点重置 |
| :free 免费模型（OpenRouter） | 每天重置，模型 ID 以 :free 结尾 |
| Free Plan 高速推理（Groq） | 按模型分别限速，每天重置 |
| Gemini API 免费层（Google AI Studio） | 每天重置，实际限额以 AI Studio 限额面板为准 |
| 每日免费 Neurons（Cloudflare Workers AI） | 00:00 UTC 重置，北京时间 08:00 |
| 桌面端每日领 Credits（Qoder） | 每天在 Qoder 桌面应用内领取 |
| 混元 Hy4 限时免费（WorkBuddy / CodeBuddy） | 活动期内每日赠送，订阅用户额度更高 |
| 每日签到积分（TRAE CN（字节跳动）） | 每天签到刷新，另有邀请积分 |
| Web Search API（MCP）每日免费（You.com） | 每天重置，通过 MCP 服务器调用 |
退避与分流
分钟级限速可以用指数退避：每次等待时间翻倍，并加一点随机抖动，避免多个客户端同时重试撞在一起。下面是通用写法（伪代码）：
import time, random
for attempt in range(5):
status = call_api() # 你的调用，返回状态码
if status != 429:
break
# 429：先判断是分钟级还是日级限速（看报错信息 / Retry-After）
# 日级限速不要重试，等到重置时间；分钟级按退避等待
wait = min(2 ** attempt + random.random(), 60)
time.sleep(wait)长期缓解办法：降低并发、把请求分散到多个厂商的额度（不要违反厂商条款，不要用多账号刷额度）。
其他：404 / 模型名错误
404 常见于 Base URL 路径重复（/chat/completions 加了两次）或模型名写错。先按厂商文档核对 Base URL 与模型名，再看是不是把 Key 填错了位置。