1
按错误码快速定位
遇到 API 报错时，先根据错误码确定问题方向，再按对应的检查清单进行排查。
2
401/403 未授权或无权限
API Key 无效、权限不足或凭证配置错误。
常见原因
- API Key 无效或已过期
- 账号未开通对应服务
- 权限不足或模型不可用
- 组织或项目受到限制
检查动作
- 确认 API Key 是否正确
- 检查账号是否开通目标模型
- 确认配置项与请求头类型
- 查看是否有地域或组织限制
修复
- 更换有效的 API Key
- 开通对应服务或提升权限
- 使用有权限的账号或组织
- 清理旧凭证后重新登录
验证
- 使用最小请求测试
- 检查是否返回 200
- 确认模型可以正常调用
3
404 资源不存在
地址错误、模型不存在或接口路径不正确。
常见原因
- Base URL 地址错误
- 模型名称不正确
- API 路径或版本错误
- 请求的资源已被删除
检查动作
- 检查 Base URL 是否正确
- 确认模型名称与控制台一致
- 核对 API 路径格式
- 查看官方文档的最新地址
修复
- 更正正确的地址和路径
- 使用存在的模型名称
- 按当前文档格式请求
- 更新到最新的接口版本
验证
- 使用正确地址重试
- 确认返回 200 响应
- 检查返回的数据格式
4
429 请求过于频繁
超出速率限制、并发限制或账户额度。
常见原因
- 请求频率超过限制
- 超出当日或每月额度
- 并发请求过多
- 短时间内大量请求
检查动作
- 查看响应头中的限制信息
- 检查控制台用量和余额
- 确认请求频率是否过高
- 查看是否有并发限制
修复
- 降低请求频率
- 增加账户额度
- 升级套餐或申请更高额度
- 优化并发请求数量
验证
- 调整后重新请求
- 确认不再出现 429
- 监控使用量避免再次触发
5
5xx 服务器内部错误
服务端异常、过载或临时不可用。
常见原因
- 服务端临时故障
- 上游服务异常
- 服务器过载
- 维护或升级中
检查动作
- 查看服务状态页面
- 确认是否为已知故障
- 检查请求参数是否正确
- 稍后使用同一请求重试
修复
- 等待片刻后重试
- 记录并反馈 request ID
- 切换备用服务或节点
- 避免立即并行重试
验证
- 间隔一段时间后重试
- 确认返回 200 响应
- 检查服务状态是否恢复
6
超时 Timeout
网络不稳定、代理异常或上游响应过慢。
常见原因
- 网络连接不稳定
- 上游服务响应慢
- 请求超时时间设置过短
- 网络防火墙或代理问题
检查动作
- 检查本地网络连接
- 确认上游服务状态
- 查看请求超时时间设置
- 检查是否有代理或防火墙
修复
- 优化网络环境
- 适当增加超时时间
- 使用稳定的网络连接
- 检查并调整代理设置
验证
- 调整后重新请求
- 确认不再超时
- 检查响应时间是否正常
7
常见终端报错示例
以下是一些常见的错误返回示例，帮助你更快定位问题。
401 错误示例
{
"error": {
"message": "Invalid API key",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}429 错误示例
{
"error": {
"message": "Rate limit exceeded",
"type": "rate_limit_error",
"code": "insufficient_quota"
}
}8
常见问题 FAQ
401 和 403 有什么区别？
401 通常表示凭证缺失、失效或请求头不正确；403 表示服务识别了身份，但当前账号、组织或模型没有访问权限。
如何设置更长的超时时间？
在客户端网络设置或配置文件中提高 timeout；同时确认问题确实是响应慢，而不是地址、代理或 TLS 连接失败。
429 错误后多久可以重试？
优先读取 Retry-After 或控制台提示。没有明确值时逐步延长等待时间，并降低并发，避免所有请求同时重试。
如果所有错误都检查过还是不行怎么办？
保留脱敏的状态码、响应正文、时间、目标地址和 request ID，再联系对应服务方；不要公开完整 API Key。
5xx 错误需要我处理吗？
多数 5xx 来自网关或上游服务。先查看服务状态并稍后复测；若持续出现，携带 request ID 和发生时间反馈。
网页能打开，为什么 API 仍然超时？
网页和 API 可能经过不同路径、代理和认证流程。需要分别检查 DNS、端口、TLS、首包时间和流式连接。