无量AI开放平台

简体中文

English

简体中文

English

主题

错误码 ​

API 错误码完整参考及解决方案。当 API 调用失败时，可据此快速定位问题原因并采取相应措施。

错误响应格式 ​

所有错误遵循统一的 JSON 结构：

json
{
  "error": {
    "code": "invalid_request",
    "message": "Request body is malformed",
    "type": "invalid_request_error",
    "request_id": "req_abc123xyz"
  }
}
字段类型说明
codestring机器可读的错误码，用于程序化处理
messagestring人类可读的错误描述
typestring错误类型分类
request_idstring请求唯一标识，提交工单时请提供此 ID

HTTP 状态码 ​

状态码类型说明解决方案
400invalid_request请求体格式错误检查字段类型和必填字段
401authentication_errorAPI Key 无效或缺失验证你的 API Key
403permission_errorAPI Key 权限不足检查 API Key 权限设置
404not_found模型或资源不存在验证模型标识是否正确
409conflict资源冲突检查请求的资源状态
422unprocessable_entity请求参数不合法检查参数值和取值范围
429rate_limit_error超出速率限制参见 速率限制
500server_error服务器内部错误使用指数退避重试
502bad_gateway网关错误稍后重试
503service_unavailable上游服务不可用稍后重试
504gateway_timeout网关超时简化请求或稍后重试

错误码详解 ​

invalid_request ​

HTTP 状态码： 400

请求体不符合 API 要求，可能是 JSON 格式错误、缺少必填字段或字段类型不正确。

常见原因：

  • 请求体不是合法的 JSON
  • 缺少 model 或 messages 等必填字段
  • 字段类型错误（如 messages 传入了字符串而非数组）

解决方案：

python
# 错误示例
{"model": "deepseek-v4-flash", "messages": "你好"}  # messages 应为数组

# 正确示例
{"model": "deepseek-v4-flash", "messages": [{"role": "user", "content": "你好"}]}

authentication_error ​

HTTP 状态码： 401

API Key 缺失、格式错误或已失效。

常见原因：

  • 未提供 Authorization 请求头
  • API Key 格式不正确（缺少 Bearer 前缀）
  • API Key 已被禁用或删除

解决方案：

bash
# 确保请求头格式正确
Authorization: Bearer sk-your-api-key-here

前往 API Key 管理 检查 Key 状态。

permission_error ​

HTTP 状态码： 403

API Key 存在但权限不足，无法访问请求的资源。

常见原因：

  • API Key 未开通对应模型的访问权限
  • 账户未通过实名认证
  • API Key 限制了特定 IP 或域名

解决方案：

  • 在 控制台 检查 API Key 的权限配置
  • 确认账户已完成必要的认证

not_found ​

HTTP 状态码： 404

请求的模型或资源不存在。

常见原因：

  • 模型标识拼写错误
  • 模型已下线或尚未开放
  • 任务 ID 不存在（异步任务查询场景）

解决方案：

  • 在 模型列表 中确认模型标识
  • 检查模型名称是否正确，注意大小写

insufficient_quota ​

HTTP 状态码： 402

账户余额不足以完成本次请求。

常见原因：

  • 账户余额为零或不足以支付本次调用费用

解决方案：

rate_limit_error ​

HTTP 状态码： 429

请求频率超出当前等级的速率限制。

常见原因：

  • 短时间内发送了过多请求
  • 并发请求数超限

解决方案：

  • 参见 速率限制 了解各等级的限额
  • 实现带抖动的指数退避重试机制
  • 如需更高限额，提交工单申请
python
import time
import random

def retry_with_backoff(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
    raise Exception("Max retries exceeded")

server_error ​

HTTP 状态码： 500

服务器内部错误，通常不是请求方的问题。

解决方案：

  • 使用指数退避重试
  • 如果持续出现，记录 request_id 并 提交工单

service_unavailable ​

HTTP 状态码： 503

上游模型服务暂时不可用，可能是维护或过载。

解决方案：

  • 等待 30 秒后重试
  • 如持续出现，可尝试切换到备用模型
  • 关注平台公告了解维护信息

常见错误场景 ​

"Model not found" ​

  • 在 模型列表 中验证模型标识
  • 检查模型是否已下线或处于 Beta 状态
  • 确认模型名称拼写正确（注意版本号和连字符）

"Insufficient quota" ​

"Rate limit exceeded" ​

  • 查看 速率限制 了解你的等级限额
  • 实现带抖动的指数退避
  • 减少并发请求数
  • 如需更高限额，升级等级或提交工单

视频生成任务失败 ​

  • 检查 prompt 是否包含敏感内容
  • 确认图片 URL 可访问（图生视频场景）
  • 适当简化 prompt 后重试
  • 如多次失败，记录 task_id 提交工单

错误处理最佳实践 ​

  1. 始终检查 error.code：用错误码（而非仅 HTTP 状态码）进行程序化处理，更精确
  2. 对可重试错误实现指数退避：429 和 5xx 错误适合重试，建议使用带抖动的指数退避
  3. 不要重试 400 错误：400 类错误表示请求本身有问题，应修复请求后重试
  4. 记录 request_id：每个错误响应都包含唯一的 request_id，提交工单时务必提供
  5. 设置合理的超时时间：视频生成等异步任务可能需要较长时间，但同步接口建议设置 30-60 秒超时
  6. 监控错误率：在应用中记录和分析错误类型及频率，及时发现异常

获取帮助 ​

如果按照以上方案仍无法解决问题：

  • 在 控制台 提交工单，附上 request_id 和错误信息
  • 查看 请求日志 追踪历史请求的详细状态