RUN7 / 知识与工具
AI API 报错排查:401、404、429、超时与跨域
先看 HTTP 状态码与请求路径,再检查认证、权限和限流。浏览器跨域失败与 Key 无效不是一回事,不能仅凭“连接失败”就反复更换 Key。
先定位是哪一类错误
| 结果 | 可能原因 | 下一步 |
|---|---|---|
| 400 / 422 | 请求体或参数不兼容 | 检查协议、必填项和输出上限字段 |
| 401 | 凭证缺失、失效或过期 | 本地核对认证请求头和 Key |
| 403 | 权限或策略限制 | 确认模型权限,不要认定一定是余额不足 |
| 404 | 路径或资源不存在 | 检查重复 /v1 和完整模型 ID |
| 429 | 限流或配额条件 | 查看错误类型及可用的 Retry-After |
| 5xx | 服务或网关异常 | 有限重试并保留请求 ID |
不同服务的错误映射可能不同,单看状态码不能确定所有原因。不要向公开客服帖子或截图粘贴完整 Key。
网络失败不等于认证失败
浏览器请求第三方接口时,对方若未允许跨域,浏览器可能不提供可读取的 HTTP 状态。DNS、TLS、扩展插件与网络连接也可能让 fetch 失败。应在本地运行相同的最小 curl 请求,判断是浏览器限制还是 API 本身的问题。
不要关闭浏览器安全限制或跳过证书校验。基础检测工具会将这类情况标为网络/跨域未确定,而不是直接判定 Key 无效。
哪些情况适合重试
临时服务异常或限流可以等待后有限重试,接口提供 Retry-After 时应遵循它。正式程序使用递增延时并加入随机抖动,设置最大次数。认证错误、参数错误应先修复再发请求。请求超时后,服务端可能仍在处理并产生费用,不能无限补发。
向客服提供有效线索
- 请求时间与时区、模型 ID、客户端版本、所选协议。
- HTTP 状态码和可获取的请求 ID。
- 本地最小请求是否成功,开启流式后有何变化。
- 脱敏的请求结构,移除认证头、私人文档与不宜公开的地址。
还没有成功发出第一轮请求时,先看 API 接入检查清单。
联系获取 Key ↗