跳到正文
九维AI开放平台使用文档

问题排查

AI API 连接失败排查:401、402、403、404、429 与 503

按错误码检查密钥、余额、授权、路径、限流和容量,使用最小请求定位工具与平台问题。

成都九维数创科技有限公司 · 文档团队更新于 约 6 分钟阅读
本页目录
  1. 先保留错误信息
  2. 按状态码排查
  3. 模型列表成功但生成失败
  4. 限流与容量拒绝
  5. 网络中断与重复提交
  6. 怎样提交有效工单

先保留错误信息#

记录 HTTP 状态码、错误码、模型 ID、请求路径和请求 ID。工具弹窗不完整时,可用最小 curl 请求查看响应;不要在工单中粘贴完整密钥。

按状态码排查#

状态常见含义优先检查
401密钥无效或被停用是否完整、是否为本站密钥、是否已撤销
402可用余额不足可用余额、冻结金额、请求规格
403模型授权或白名单限制账户模型中心、API Key 允许模型
404路径、模型或任务不存在重复 /v1、完整模型 ID、任务归属
429速率超限RPM、工具并发及 Retry-After
502上游调用或读取失败请求 ID、上游状态及原请求记录
503容量不足或没有可用渠道具体错误码、Retry-After、客服反馈

错误码比单独状态更具体。例如 model_not_assigned 表示账户资源未分配,model_not_allowed 表示密钥白名单限制,generation_capacity_exceeded 表示当前生成容量已满。

模型列表成功但生成失败#

模型列表是只读请求,生成还需符合权限、余额、协议、能力和价格规格。先用一条短文本和较小输出上限测试,再逐项打开工具调用或图像能力。

如果 API 最小请求成功,但桌面工具失败,重点检查客户端字段含义、模型 ID、重复路径和特殊参数。

限流与容量拒绝#

读取 Retry-After 并降低并发,不要通过反复创建 API Key 或毫秒级重试绕过限制。Agent 工具一次任务可能发送多条模型请求,应同时核对其并发设置。

网络中断与重复提交#

网络超时并不确认上游未执行。先查看用量明细和原任务状态,避免盲目重放付费 POST。异步任务应继续查询原 task ID,不要直接重新生成。

怎样提交有效工单#

提供工具名称与版本、发生时间、模型与规格、HTTP 状态、脱敏错误正文及请求/任务 ID。说明最小 API 请求是否成功、是否只在流式或某项高级功能失败。

这些信息帮助区分配置错误、模型能力、线路异常与账务状态。可以直接前往客服工单。

准备好开始了吗?

在控制台选择账户可用模型,先用一条简单请求验证配置。

打开 Playground