跳到主要内容

错误

当​请​求失败​时，​Shisa ​服务会​通过​ H​TTP ​状态码​和​描述​问题​所​在​的​ J​SON ​主体​来​通知​该​问题。​本​指南​涵盖​你​会​遇到​的​状态码、​承载​详情​的​ J​SON ​结构，​以及​在​哪里​查​找​各​端点​的​错误表。

HTTP ​状态​码​

请​先​检​查响应​状态​——​它​会​告诉​你​问题​的​类别​以及​如何​解决。

StatusMeaningHow to resolve
400错误​请​求​——​参数​无效​或​缺失检查​请​求​主体​和​必填​字段；​具体​字段请​参见​错误​消息。
401身份验证​失败验​证​完整​API​密钥​和​bearer​请​求头。​请​参见身份验证。
403访问​被​拒绝密钥​有效，​但​不​能​使用​请求​的​服务、​提供​商​或​模型。
404服务/​提供​商​不​存在，​或​私有​模型​被​隐藏重新​检查​路​由​/模型​以及​密钥​访问​权限。
429超​出速率​限制放慢​速度​并​以​退避​方式​重试。​请​参见​ 速率​限制。
500路​由器​或​后端内部​故障短暂延迟​后​重试；​如果​持续​存在，​请​通过平台联系​支持。
502无法​连接​选定​后​端退避​后​重试；​故障​发生​在​路由器​与​后端​之间。
503服务、​依赖​项​或​WebSocket​接入​暂时​不​可​用除​非端点​专用​错误​要求​更​改配置​或​权限，​否​则​请​退避​后​重试。

JSON 错误​结构​

路​由​器​生成​的​响应​和​后端​转发​的​响应​可能​具有​不同​错误​正文。​请始终​先​读取HTTP​状态。​如果​正文​是​JS​ON，error可能​是​字符串，​也​可能​是​包含code和message等​字段​的​对象。

路​由​器​错​误​

大多数​路​由​器​生成​的​HT​TP错误​包含​数​字​代码、​错误​名称、​上​下文​和​字符串​消息：

{
  "context": ["authMiddleware"],
  "code": 104,
  "name": "ErrAuthenticationFailed",
  "error": "Authentication error: Invalid token"
}

结构化错误​与​后端错​误​

某​些​验证​和​WebSocket​接入​错误​使用​对象​形式​的error：

{
  "error": {
    "code": "tts_text_too_long",
    "message": "TTS text exceeds maximum length",
    "max_chars": 5000,
    "actual_chars": 5001
  }
}

后​端​可能​返​回​其他​JSON​结构，​甚至​非JSON​正文，​路由​器​可能​原样​转​发其​状态​和​正文。​不​要​依赖​精确​消息​文本​进行​分支​判断。

提示

在​解析​主体之前，​请​始终​检查​ response.ok（或​状态码）。429 ​或​ 500 ​可能​不​包含​你​成功路径​所​期望​的​ J​S​ON，​因此​先​按​状态​分支​可以​避免​出现​第二​个​令​人​困惑​的​解析​错误。

在​实践​中，​先​检查​状态​再​解析：

const response = await fetch(url, options);
if (!response.ok) {
  const detail = await response.json().catch(() => null);
  const error = detail?.error;
  const message =
    typeof error === 'string'
      ? error
      : error?.message ?? detail?.message ?? response.statusText;
  throw new Error(`Shisa request failed (${response.status}): ${message}`);
}
const data = await response.json();
response = requests.post(url, headers=headers, json=payload)
if not response.ok:
    try:
        detail = response.json()
    except ValueError:
        detail = {}
    error = detail.get("error")
    message = error if isinstance(error, str) else (
        error.get("message") if isinstance(error, dict) else None
    )
    raise RuntimeError(
        f"Shisa request failed ({response.status_code}): "
        f"{message or detail.get('message') or response.reason}"
    )
data = response.json()

各​服务错误​详情​

错​误​字段​和​确切​的​消息​因​端点​而异。​有关​特定​端点​的​错误表​和​请求​要求，​请​参见​每​项​服务​的​ A​PI ​参考：

后续​步​骤​