错误码参考

SilvaMux 的错误格式取决于接口类型。本页汇总通用错误格式、模型调用错误码与重试建议。

Gateway API 错误（模型调用）

对话、图片、视频等模型调用接口的错误格式由模型协议决定，分 OpenAI / Anthropic / Gemini / Volcengine 四种渲染形状，code 字符串统一。

{
  "error": {
    "message": "具体错误信息",
    "type": "gateway_error",
    "code": "ERROR_CODE"
  }
}

模型侧返回 4xx/5xx 时，SilvaMux 会脱敏后透传错误响应，HTTP 状态码保持一致，此时不会产生扣费。

Gateway API 错误码

对话、图片、视频模型调用共用下列错误码：

错误码	HTTP	说明
`MODEL_REQUIRED`	400	请求体缺少 `model` 字段
`MODEL_NOT_FOUND`	400	模型不存在或不可用
`INVALID_REQUEST`	400	请求参数无效
`INVALID_REQUEST_BODY`	400	请求体解析失败
`UNAUTHORIZED`	401	认证失败（API Key/JWT 无效）
`MODEL_ACCESS_DENIED`	403	组织缺少该模型所需权限标志
`INSUFFICIENT_BALANCE`	402	余额不足
`PRE_DEDUCT_FAILED`	400/402	预扣费失败（参数错误=400，落库失败=402）
`RATE_LIMITED`	429	触发限流（见限流）
`UPSTREAM_UNAVAILABLE`	502	模型侧请求发送失败
`UPSTREAM_HTTP_ERROR`	502	模型侧返回 4xx/5xx
`UPSTREAM_PROVIDER_ERROR`	502	模型侧业务错误
`UPSTREAM_INVALID_RESPONSE`	502	模型侧响应无法解析
`INTERNAL`	500	内部错误

图片生成特有

错误码	HTTP	说明
`REQUEST_TOO_LARGE`	413	请求体超过 64MB
`CONCURRENCY_LIMIT_EXCEEDED`	429	图片生成并发上限

视频与任务特有

错误码	HTTP	说明
`INVALID_CALLBACK_URL`	400	回调 URL 无效
`CONCURRENCY_LIMIT_EXCEEDED`	429	视频生成并发上限

取消任务的错误：

HTTP	错误码	说明
404	`NOT_FOUND`	任务不存在
409	`INVALID_STATE`	任务不在 queued 状态
502	`UPSTREAM_CANCEL_FAILED`	模型侧取消失败

Billing / Business API 错误（管理接口）

账户、计费、自有素材等管理接口使用 RFC 7807 风格：

{
  "status": 400,
  "detail": "具体错误信息",
  "type": "tag:hub,2026-03:ERROR_CODE"
}

验证错误包含 errors 数组：

{
  "status": 422,
  "detail": "validation failed",
  "type": "tag:hub,2026-03:VALIDATION_FAILED",
  "errors": [{"location": "body.email", "message": "required"}]
}

客户查询接口（余额/用量）的错误码见查询余额与查询用量。

重试建议

HTTP 状态码	建议
400	不要重试，修正请求参数
401	不要重试，检查认证信息
402	不要重试，充值后再试
403	不要重试，联系管理员
429	等待后重试，建议指数退避
500	可以重试，建议间隔 1-5 秒
502	可以重试，模型侧暂时不可用

请求 ID

每个请求返回 X-Request-Id header（格式 REQ-xxxx）。排查问题时提供此 ID。你也可以在请求中自行设置 X-Request-Id，系统会沿用。