HTTP 状态码

调用词驿 API 时可能遇到的 HTTP 状态码及其含义。

成功

状态码	含义
200 OK	请求成功（流式响应也是 200）

客户端错误（4xx）

状态码	含义	排查
400 Bad Request	请求参数错误	检查请求体 JSON 格式、必填字段、模型名
401 Unauthorized	认证失败	API Key 无效、过期或被删除；检查 Authorization 头
402 Payment Required	余额不足	令牌或账户额度耗尽，请充值或更换令牌
403 Forbidden	无权限	令牌无权访问该模型/分组，或被禁用
404 Not Found	路径或模型不存在	检查接口路径、模型名拼写
429 Too Many Requests	触发限流	降低请求频率，或联系提升配额

服务端错误（5xx）

状态码	含义	排查
500 Internal Server Error	服务内部错误	通常是上游渠道异常，可重试或换模型/分组
502 / 504	网关错误 / 超时	上游无响应，重试或换渠道
503 Service Unavailable	无可用渠道	该模型当前无可用上游，检查渠道状态

错误响应体

错误时返回 JSON，关键字段：

{
  "error": {
    "message": "无可用渠道",
    "type": "upstream_error",
    "code": "no_available_channel"
  }
}

• message：人类可读的错误说明。
• code：机器可读的错误码，便于程序处理。

重试建议

对 5xx 与 429 类瞬时错误，建议指数退避重试（如间隔 1s / 2s / 4s，最多 3 次）。对 4xx（除 429）业务错误，不要重试，应修正请求。