立即注册

错误码与限流

错误码与限流

平台 API 提供 跨入口稳定 的错误标识，便于统一处理：

字段命名（因协议略有差异）说明
字符串错误码error_code / errorCode / code主键，snake_case 或 camelCase
数字错误码error_no / errorNo与字符串码 1:1 绑定 的 4 位数字，便于分段聚合
可读说明error / message面向用户的错误文案

50xx 上游业务类（内容违规、参数无效、素材不可用等）会 完整回传 上游/审核原文到 error / message，便于排查；平台通道敏感问题（上游配额、鉴权失败、OSS 转存、轮询超时等）统一映射为 service_unavailable（4001），不暴露上游细节。

1. 稳定错误码一览

段位：10xx 鉴权/访问 · 20xx 限流 · 30xx 账单 · 40xx 路由/平台 · 50xx 上游业务

10xx — 鉴权 / 访问

error_codeerror_noHTTP说明建议处理
invalid_request1001400 / 401参数无效、API Key 无效检查请求体与 Key
model_not_found1002404模型不存在或未上架核对 modelKey / model
access_denied1003403无该模型访问权限控制台确认授权
tenant_arrears1004403租户欠费充值或联系运营
account_frozen1005403账户冻结联系运营
user_blacklisted1006403用户黑名单联系运营
user_cancelled1007403用户已注销—

20xx — 限流

error_codeerror_noHTTP说明建议处理
rate_limited2001429平台 RPM/TPM/并发超限退避重试
upstream_rate_limited2002429上游供应商限流降低频率或换模型

30xx — 账单

error_codeerror_noHTTP说明建议处理
insufficient_balance3001402账户余额不足控制台充值
billing_unavailable3002503计费服务暂不可用稍后重试

40xx — 路由 / 平台

error_codeerror_noHTTP说明建议处理
service_unavailable4001503服务暂不可用、上游 5xx、failover 耗尽、上游配额/鉴权隐藏、OSS 转存失败、轮询超时稍后重试
routing_temporarily_unavailable4002503路由暂不可用稍后重试

50xx — 上游业务（异步任务失败主要落在此段）

error_codeerror_noHTTP说明建议处理
upstream_invalid_request5001400上游业务失败（未命中更细分类）对照 模型接入说明 与厂商文档
content_policy_violation5002400内容/审核/合规拒绝（无法区分 input/output 时的兜底）修改 prompt 或素材
upstream_invalid_parameter5003400参数结构无效（格式、缺字段、类型错误等，非内容违规）修正请求参数
content_policy_input_violation5004400输入侧违规（prompt、入参图片/视频/音频触敏或违规）修改输入内容后重试
upstream_resource_unavailable5005400素材/URL 不可用、文件不存在检查资源 URL 或重新上传
upstream_capability_unsupported5006400模型/能力不匹配（分辨率、时长、同步/异步等）换模型或调整能力参数
upstream_task_expired5007400上游异步任务过期重新提交任务
content_policy_output_violation5008400生成结果违规（输出触敏、暴力/涉黄、版权限制等）调整 prompt 或重新生成

内容违规 vs 参数无效：若参数格式/字段本身有问题 → upstream_invalid_parameter（5003）；若参数结构正确但 内容 触敏或违规 → content_policy_*（5002/5004/5008）。优先根据 error_code / error_no 判断，其次阅读 message 原文。

2. 各协议错误形态

OpenAI 兼容（/v1/chat/completions 等）

HTTP 4xx/5xx，body 示例：

{
  "error": {
    "message": "输入文本包含敏感词，请修改后重试",
    "type": "invalid_request_error",
    "code": "content_policy_input_violation",
    "error_no": 5004
  }
}

流式错误：SSE event: error + 上述 error body + data: [DONE]。

Anthropic 兼容（/v1/messages）

HTTP 4xx/5xx，body 示例：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "输入文本包含敏感词，请修改后重试"
  }
}

Anthropic 形态以 message 为主；同步/查单类 gRPC 响应同时带 errorCode + errorNo。

异步任务 API（/api/ai/tasks）

提交失败或查单 status: failed / error 时（camelCase）：

{
  "taskId": "12345__my-video-001",
  "status": "failed",
  "error": "输入音频文件不存在",
  "errorCode": "upstream_resource_unavailable",
  "errorNo": 5005
}

提交校验失败示例：

{
  "taskId": "",
  "status": "error",
  "error": "Must provide one of: videoParams, imageParams, textParams",
  "errorCode": "invalid_request",
  "errorNo": 1001
}

Webhook 回调

失败时 payload 为 snake_case，含 error、error_code、error_no（详见 Webhook）。

3. 限流体系

平台多层限流，命中任一层即可能返回 rate_limited（2001）。

层级说明
账号 RPM账号整体每分钟请求数
模型 RPM单模型每分钟请求数
模型 TPM单模型每分钟 Token
并发同时 in-flight 请求数

控制台 密钥管理 页展示模型 RPM / TPM 参考值。

4. 重试建议

error_code / 段位是否重试策略
rate_limited / upstream_rate_limited（20xx）是指数退避 + jitter
service_unavailable / billing_unavailable / routing_temporarily_unavailable（40xx）是有限次数重试
insufficient_balance（30xx）否充值后再调
invalid_request / access_denied / model_not_found（10xx，除欠费类）否修正参数或权限
tenant_arrears 等账户状态（10xx）否联系运营或充值
content_policy_input_violation（5004）否修改 输入 prompt/素材
content_policy_output_violation（5008）可有限重试调整 prompt 后 重新提交；同一输入可能再次触发
content_policy_violation（5002）否修改内容
upstream_invalid_parameter / upstream_capability_unsupported（5003/5006）否修正参数或换模型
upstream_resource_unavailable（5005）否检查素材 URL
upstream_task_expired（5007）否重新提交新任务

5. Request ID 排查

请求失败时记录：

  • 响应头 x-request-id（异步 submit / poll / cancel 均会回显）
  • 数据统计 对应时间段
  • taskId、callbackId；联系平台时优先提供 submit 时的 x-request-id
  • 失败时的 errorCode + errorNo，以及 error / message 原文

联系平台支持时一并提供。

相关文档