HTTP 状态码

状态码只能缩小范围，最终仍应结合错误正文和控制台日志判断。

状态码	常见方向	建议
400	请求体或参数不兼容	从最小请求开始，检查模型能力和字段格式
401	鉴权失败	检查 Key、请求头和环境变量
403	权限或策略拒绝	检查 Key 状态、模型、IP、分组和路由
404	路径不匹配	检查 Base URL、/v1 和客户端自动拼接
408 / timeout	网络或处理超时	区分连接、首字节和总体超时
413	请求体过大	减少输入、附件或上传体积
429	限流或额度相关	降低并发、检查额度并受控退避
5xx	平台或上游临时错误	查看日志，有限重试，不无限重放

400

常见于协议字段不兼容、模型不支持某参数、请求体结构错误。不要一次带入大量高级字段。

401

通常与 API Key 或鉴权头有关。先用 GET /v1/models 做最小验证。

403

比 401 更可能是“凭证存在，但当前策略不允许”。检查模型限制、IP、分组和路由。

404

最常见是 Base URL 填错或客户端自动追加路径。确认最终 HTTP URL。

413

服务端有请求体大小保护。图片、音频、超长 Base64 或大型上下文应控制体积。

429

429 不应只理解为“请求太快”。还可能与模型、上游配额或账户额度有关。先查看错误正文和平台日志。

5xx

对临时 5xx 可以有限退避重试。对于可能计费的生成请求，要考虑上游已经接收但客户端未收到响应的情况，避免盲目重复。