错误码

对话接口（Gateway API）使用 OpenAI 兼容错误格式：

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

Anthropic / Volcengine 格式的错误形状各有差异，但 code 字段一致。

常见错误码

错误码	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	内部错误

模型侧错误透传

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

重试建议

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

每个请求返回 X-Request-Id header（格式 REQ-xxxx），排查问题时提供此 ID。