错误码与限流

两类错误结构

普通接口（对话、嵌入、图像、语音、重排序等）统一返回 OpenAI 风格错误：

{
  "error": {
    "message": "对用户可读的错误描述",
    "type": "错误类型",
    "param": "出错的参数名（可为空）",
    "code": "错误码"
  }
}

异步任务接口（视频生成等）的错误结构随入口不同，请按 code / message 处理，不要只依赖 HTTP 状态码：

入口	非 2xx 响应体（示例）
OpenAI 兼容（/v1/videos、/v1/video/generations）	{"code":"invalid_size","message":"...","data":null}
MiniMax v2 原生（/v2/video_generation）	{"type":"error","error":{"type":"bad_request_error","message":"...","http_code":"400"}}
MiniMax v1 原生（/v1/video_generation）	{"base_resp":{"status_code":400,"status_msg":"..."}}

异步任务的详细错误码见视频生成 · 错误处理与限制。

HTTP 状态码与常见错误

状态码	含义	常见 error.code
400	请求参数错误	invalid_request、json_marshal_failed、read_request_body_failed 等
401	认证失败：Key 缺失 / 无效 / 已删除 / 已禁用 / 已过期	code 可能为空，按 message 判断
402	套餐超量预算相关限制	coding_plan_overage_* 等
403	额度不足、无权限	insufficient_user_quota、access_denied（部分场景 code 为空，按 message 判断）
404	接口或资源不存在	code 按响应体为准
413	请求体过大	以响应体为准
429	触发限流、异步任务并发达到上限或上游临时繁忙	async_task_concurrency_limit 或 code 为空
503	模型暂无可用渠道 / 上游异常	model_not_found 等
5xx	服务端 / 上游异常	upstream_error（type）、do_request_failed、bad_response_status_code 等

常见错误码对照

error.code	含义与处理
invalid_request	请求体格式错误或参数非法，按 message 修正后重试
insufficient_user_quota	余额 / 额度不足（403），充值或等待额度发放后自动恢复
access_denied	无权限访问：如 IP 不在令牌白名单、令牌未授权该模型（403），检查控制台该 Key 的限制配置
model_not_found	模型不可用、无可用渠道（503）或不在令牌白名单（403），检查 model 是否在 GET /v1/models 列表中
async_task_concurrency_limit	单账号异步任务（视频等）并发达到上限（429），等待已有任务完成后再提交；message 给出当前占用数与上限
sensitive_words_detected	内容触发安全审核，调整请求内容
do_request_failed / bad_response_status_code	请求 / 读取上游响应失败，稍后重试；持续失败请提交工单

说明：不同模型、不同调用链路的错误码可能不同，以实际响应为准；message 字段始终是对用户最友好的描述，排障时优先阅读它。message 末尾通常附带 (request id: ...)，提交工单时请一并提供。

限流说明

平台限流来自三个不同层面，其响应形态不同：

来源	响应	处理
全局 IP 限流（保护性，按客户端 IP 计数）	429，无响应体，带 Retry-After 响应头（秒）	按 Retry-After 等待后重试
账号 / 分组请求限流（管理员按分组配置的每分钟额度）	429，OpenAI 错误体，code 为空，message 说明限流原因与上限	降低调用频率、指数退避
异步任务并发上限	429，code 为 async_task_concurrency_limit	等已有视频 / 音乐任务完成后再提交

额度不足返回的是 403 insufficient_user_quota，不是 429；上游临时繁忙（"当前分组上游负载已饱和"等提示）可能返回 429 或 5xx，按 message 区分并稍后重试。

重试建议

状态码	是否建议重试	策略
400 / 401 / 403 / 404	否（先修正请求）	按 message 修正参数、密钥或权限后再试
429	是	指数退避（如 0.5s → 1s → 2s …）；优先读取 Retry-After（如有）；异步并发上限则等待任务完成
5xx	是	短退避重试 2~3 次，持续失败请带 request id 提交工单

异步任务提交的重试陷阱

POST /v1/videos 等提交接口是"可能产生计费"的写操作：网络超时或 429 / 5xx 时，上一次的提交可能已经成功下单。重试前请确认没有拿到过 task_id；查询接口（GET /v1/videos/{task_id}）是幂等的，可放心重试。

示例：额度不足

curl -i https://confluia.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}]}'

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "预扣费额度失败, 用户剩余额度: ..., 需要预扣费额度: ...",
    "type": "insufficient_user_quota",
    "code": "insufficient_user_quota"
  }
}

充值后该错误自动消失，无需改代码。