错误处理

SilvaMux 使用两种错误格式，取决于你调用的是 Gateway API 还是 Billing API。

Gateway API 错误

Gateway API（模型调用接口）使用 OpenAI 兼容的错误格式：

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

常见错误码

错误码 HTTP 状态码 说明
MODEL_REQUIRED 400 请求体缺少 model 字段
MODEL_NOT_FOUND 400 模型不存在或不可用
MODEL_ACCESS_DENIED 403 组织没有访问该模型的权限
UNAUTHORIZED 401 认证失败
RATE_LIMITED 429 请求频率超出限制
INSUFFICIENT_BALANCE 402 余额不足
PRE_DEDUCT_FAILED 400/402 预扣费失败
UPSTREAM_UNAVAILABLE 502 上游服务不可用
INTERNAL 500 内部错误

上游错误透传

当上游模型供应商返回 4xx/5xx 错误时，SilvaMux 会将错误响应原样透传（敏感信息会被脱敏处理），HTTP 状态码保持一致。此时不会产生扣费。

Billing API 错误

Billing 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 状态码 说明
INVALID_REQUEST_BODY 400 请求体格式错误
VALIDATION_FAILED 422 字段验证失败
MISSING_AUTH_TOKEN 401 缺少认证 token
INVALID_TOKEN 401 token 无效
TOKEN_EXPIRED 401 token 已过期
REFRESH_TOKEN_INVALID 401 refresh token 无效或已过期
MEMBERSHIP_NOT_FOUND 403 不是该组织成员
ORGANIZATION_NOT_FOUND 404 组织不存在
PROJECT_NOT_FOUND 404 项目不存在
API_KEY_NOT_FOUND 404 API Key 不存在
INTERNAL 500 内部错误

重试建议

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

请求 ID

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