跳到主要内容

错误

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

HTTP ​状态​码​

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

StatusMeaningHow to resolve
400错误​请​求​——​参数​无效​或​缺失检查​请​求​主体​和​必填​字段；​具体​字段请​参见​错误​消息。
401身份验证​失败验​证​你​的​ A​PI ​密钥​和​各​服务​的​请​求头​形式。​请​参见​ 身份验证。
429超​出速率​限制放慢​速度​并​以​退避​方式​重试。​请​参见​ 速率​限制。
500服务器​错误​或​服务未​就​绪短暂延迟​后​重试；​如果​持续​存在，​请​通过​ 平台 ​联系​支持。

JSON 错误​结构​

错误​主体​在​各​服务​中​有​两​种​结构。​请始终​先​读取 HTTP ​状态，​然后​解析​主体​以​获取​人类​可读​的​ error ​字段。

简单错误​

某些​端点会​返回​一​个​紧凑​的​主体，​包含​数​字 code ​和​ error ​消息。​例如，​一​个​未​附带​音频​的​ A​SR ​请​求：

{
  "code": 400,
  "error": "No audio data provided"
}

身份验证错​误​

身份验证​失败​（见于​ A​S​R ​和​ TTS）​会​返回​一​个​更​丰富​的​主体，​其中​还​标识​了​中​间​件​和​一​个​命名​的​错误​类型：

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

Invalid token 错误​几乎​总是​意味​着​该​服务​的​ Authorization ​请​求头​有​误​——例如 ASR ​或​翻译​缺少​ shsk: ​前缀。​请​查阅 各​服务​请​求头​约定。

提示

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

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

const response = await fetch(url, options);
if (!response.ok) {
  const detail = await response.json().catch(() => ({}));
  throw new Error(`Shisa request failed (${response.status}): ${detail.error ?? 'unknown error'}`);
}
const data = await response.json();
response = requests.post(url, headers=headers, json=payload)
if not response.ok:
    detail = response.json() if response.content else {}
    raise RuntimeError(f"Shisa request failed ({response.status_code}): {detail.get('error', 'unknown error')}")
data = response.json()

各​服务错误​详情​

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

后续​步​骤​