HTTP 状态码及其含义

无忧引擎尽量保持与上游及兼容协议一致的 HTTP 状态码。排查问题时，应同时查看响应体中的 error.message 或 message。

成功状态

状态码	含义	处理建议
`200`	请求成功	正常解析响应

流式请求通常先返回 200，随后通过 SSE 持续传输数据。

状态码	含义	常见原因	处理建议
`400`	请求参数错误	JSON 格式错误、缺少必填字段、参数不受模型支持	检查请求体和模型参数
`401`	未通过身份验证	API Key 缺失、错误、已删除或鉴权格式不正确	检查 `Authorization`、`x-api-key` 或 `x-goog-api-key`
`403`	无访问权限	用户分组、令牌或渠道没有模型权限	检查分组、模型授权和 API Key 限制
`404`	资源不存在	接口路径错误、模型名称错误或模型尚未启用	查询 `GET /v1/models` 并核对路径
`408`	请求超时	请求处理时间超过限制	缩短输入、降低输出上限或重试其他渠道
`409`	请求冲突	重复任务或当前状态不允许该操作	根据响应信息调整请求
`413`	请求体过大	文本、图片或上下文超过网关限制	压缩或拆分输入内容
`422`	参数可以解析但无法处理	参数组合不合法或模型不支持该能力	删除不兼容参数后重试
`429`	请求过多或额度受限	RPM/TPM/并发限制、账户余额不足或上游限流	降低并发、检查余额并进行退避重试

以下错误通常可以进行有限次数重试：

408, 429, 500, 502, 503, 504

建议：

单次请求最多重试 1～2 次。

使用指数退避，例如 0.5 秒、1 秒。

不要自动重试 400、401、403、404 等确定性错误。

流式请求已经输出部分内容后，不要直接拼接重试结果，应整次重新生成或交由业务层处理。

保存请求时间、模型名称、状态码和响应错误，方便在无忧引擎使用日志中定位。