API 401 / 429 报错排查

401 和 429 是 API 调用中最常见的两类错误。401 通常表示认证没有通过，常见原因包括 API Key 不完整、Authorization 格式错误、复制时带入空格或使用了已经删除的密钥。429 则更偏向额度、频率、套餐、模型限流或上游繁忙。排查时不要只看状态码，要同时看错误 JSON、模型名称、请求时间和账户额度。

401 Unauthorized 怎么排查

先确认请求头是否使用 Authorization: Bearer sk-your-api-key，Bearer 和密钥之间需要有一个空格。不要把完整密钥放在 URL 参数里，也不要把密钥写进公开前端代码。

如果 SDK 已经配置过默认密钥，仍然报 401，可以重新创建一个测试密钥，并用最小请求验证。复制密钥时注意不要多复制换行、中文标点、全角空格或隐藏字符。

429 Too Many Requests 怎么排查

429 不一定只是请求太快，也可能是账户余额不足、套餐额度耗尽、模型渠道临时限流或上游服务繁忙。建议先降低并发和请求频率，再检查账户余额、套餐状态和模型是否可用。

如果只有某个模型频繁 429，而其他模型正常，通常更像模型渠道侧问题。可以先切换到同类轻量模型完成测试，再把请求时间、模型名称和错误内容提供给客服排查。

联系客服前准备哪些信息

为了更快定位问题，请提供调用时间、模型名称、接口路径、HTTP 状态码、错误 JSON 和简化后的请求示例。不要发送完整 API Key、Authorization Header 或账号密码。

如果是偶发 502、524、429 等问题，建议同时提供大致耗时和是否已经扣费。这样可以区分是客户端配置问题、额度问题，还是上游模型渠道临时异常。

使用步骤

检查 API Key 是否完整，并确认 Authorization Header 格式正确。
确认 OpenAI 兼容调用的 Base URL 使用 https://aigexapi.com/v1。
查看账户余额、套餐剩余额度和当前选择的模型名称。
降低并发，先用小请求测试，再恢复正式任务。
仍然失败时，保留错误内容和请求时间联系站内客服。

常见问题

401 一定是密钥错误吗？

大多数情况和密钥或认证格式有关，也可能是复制时多了空格、密钥已删除或客户端使用了旧配置。

429 一定是请求太快吗？

不一定。余额不足、套餐额度耗尽、模型限流、上游繁忙都可能表现为 429。

排查时能把完整 Key 发给客服吗？

不要发送完整密钥。只需要提供模型、时间、错误码和脱敏后的请求示例。