错误状态码自检说明

本文用于帮助用户快速判断请求失败的常见原因。
注意： 状态码的具体含义可能因中转服务、上游模型服务、网关或代理配置不同而有所差异，请同时参考响应中的错误信息、请求 ID 和相关响应头。

一、4xx：请求、认证、权限或参数问题

4xx 通常表示客户端请求存在问题，但也可能由中转服务的鉴权、路由、WAF 或错误映射配置引起。遇到 4xx 时，请先检查请求地址、API Key、模型名称、请求格式和请求参数。

400 Bad Request：请求格式错误

请求无法被服务器正确解析或处理，例如：

JSON 语法错误；

字段名拼写错误；

缺少必填字段；

参数类型错误；

参数格式不符合接口要求；

模型名称或请求结构不符合接口规范。

如果 JSON 语法正确，但参数之间的组合不符合要求，也可能返回 400 或 422，具体以接口实现为准。

401 Unauthorized：身份认证失败

请求没有提供有效的身份认证信息，例如：

没有携带 API Key；

API Key 错误、过期或已失效；

Authorization 请求头格式错误；

忘记添加 Bearer 前缀；

API Key 前后存在多余空格或不可见字符。

常见请求头格式如下：

403 Forbidden：请求被拒绝

服务器已经理解请求，但拒绝执行，例如：

API Key 没有访问该模型或接口的权限；

账户被禁用或受到策略限制；

IP 地址被限制；

请求触发安全策略或 WAF；

当前账户没有对应服务权限；

账户余额、额度或套餐状态不满足平台要求。

不同平台对“额度用完”的处理方式可能不同，也可能返回 403、429 或其他平台自定义错误，请以实际错误信息为准。

404 Not Found：资源不存在

请求的资源不存在或无法被当前接口找到，例如：

URL 路径写错；

接口版本写错；

模型名称写错；

请求了不存在的部署、渠道或资源；

上游服务没有提供该模型；

服务端将无权限访问的资源隐藏为 404。

因此，404 不一定只是 URL 路径错误，也请检查模型名称和接口版本。

405 Method Not Allowed：请求方法不支持

请求使用了接口不支持的 HTTP 方法，例如：

对只支持 POST 的接口使用了 GET；

对只支持 GET 的接口使用了 POST；

请求方法与接口文档要求不一致。

408 Request Timeout：请求接收超时

服务器在规定时间内没有收到完整的请求，常见原因包括：

网络连接不稳定；

上传内容速度过慢；

客户端发送请求中途卡住；

代理或网关等待客户端数据超时。

这通常表示请求上传阶段超时，不等同于模型推理超时。

413 Content Too Large：请求内容过大

单次 HTTP 请求体超过了限制，例如：

文本内容过长；

图片或文件过大；

base64 编码后的图片过大；

携带的历史消息过多；

请求体超过中转服务、反向代理或上游接口限制。

注意： HTTP 请求体大小限制和模型上下文长度限制不是一回事。上下文 Token 超限时，服务商可能返回 400、413、422 或其他错误。

415 Unsupported Media Type：请求格式不支持

请求的 Content-Type 不符合接口要求，例如：

应使用 application/json，却发送成了其他格式；

上传文件时使用了错误的媒体类型；

接口要求 multipart/form-data，但客户端发送了普通 JSON；

图片格式或文件格式不受支持。

422 Unprocessable Content：请求语义无法处理

JSON 语法正确，但参数语义不符合接口要求，例如：

参数值超出允许范围；

参数之间互相冲突；

传入了不支持的模型参数；

消息角色或消息结构不符合要求；

图片、工具调用或响应格式配置不合法。

不同平台可能将此类问题返回为 400，请以实际错误信息为准。

429 Too Many Requests：请求过于频繁或额度受限

常见原因包括：

请求频率过高；

并发数超过限制；

API Key 或账户触发速率限制；

单位时间内 Token 使用量超过限制；

上游账户额度或配额已用完。

如果响应中包含 Retry-After，请等待指定时间后再重试。收到 429 后不要立即高频重试，否则可能持续触发限制。

二、5xx：中转服务、上游服务或网络链路问题

5xx 通常表示请求本身没有明显问题，但中转服务、网关、上游模型服务或网络链路出现异常。

500 Internal Server Error：服务器内部错误

服务器内部发生未预期异常，例如：

程序运行错误；

数据库异常；

配置读取失败；

内部服务之间调用失败；

上游错误未能被正确分类。

此类问题通常需要服务商排查日志。用户可以提供请求时间、请求 ID 和完整错误信息，帮助定位问题。

501 Not Implemented：功能未实现或接口不支持

当前服务暂未实现请求使用的功能、接口或 HTTP 方法。

502 Bad Gateway：上游响应异常

中转网关作为代理请求上游服务时，没有得到有效响应，例如：

上游服务连接失败；

上游服务返回了无效响应；

上游服务提前断开连接；

上游服务异常关闭；

网关与上游之间的协议或配置不兼容。

502 不仅仅表示网关配置错误或上游服务宕机，也可能表示上游返回内容异常。

503 Service Unavailable：服务暂时不可用

服务当前暂时无法处理请求，例如：

服务过载；

上游模型服务容量不足；

服务正在维护；

请求正在排队；

临时限流或资源不足。

这类错误通常可以稍后重试，但应使用指数退避，不要立即大量重试。

504 Gateway Timeout：网关等待上游超时

中转网关已经向上游发起请求，但上游服务未能在规定时间内返回结果，例如：

模型推理时间过长；

上游服务繁忙；

网络链路延迟过高；

上游接口处理超时；

网关自身超时时间设置过短。

三、用户自检清单

遇到错误时，请依次检查：

请求 URL 和接口版本是否正确；

请求方法是否符合接口要求；

Authorization 请求头是否正确；

Content-Type 是否正确；

JSON 是否能够正常解析；

model 名称是否正确；

请求文本、图片、文件或历史上下文是否过大；

是否超过并发、频率或额度限制；

是否携带完整的错误信息、请求时间和 Request ID。

四、重试建议

通常不建议无条件重试

以下错误一般需要修改请求、认证信息或账户状态后再尝试：

400

401

403

404

413

415

422

可以稍后重试

以下错误在确认请求具有可重试性质时，可以稍后重试：

408

429

500

502

503

504

522

524

重试时建议：

使用指数退避；

增加随机抖动，避免大量客户端同时重试；

优先遵循响应中的 Retry-After；

限制最大重试次数；

流式输出已经开始后，不要盲目重试，以免造成重复生成或重复扣费。

五、说明

状态码只能帮助判断错误的大致类别，不能单独作为最终结论。

连接错误原因自检

错误状态码自检说明#

一、4xx：请求、认证、权限或参数问题#

400 Bad Request：请求格式错误#

401 Unauthorized：身份认证失败#

403 Forbidden：请求被拒绝#

404 Not Found：资源不存在#

405 Method Not Allowed：请求方法不支持#

408 Request Timeout：请求接收超时#

413 Content Too Large：请求内容过大#

415 Unsupported Media Type：请求格式不支持#

422 Unprocessable Content：请求语义无法处理#

429 Too Many Requests：请求过于频繁或额度受限#

二、5xx：中转服务、上游服务或网络链路问题#

500 Internal Server Error：服务器内部错误#

501 Not Implemented：功能未实现或接口不支持#

502 Bad Gateway：上游响应异常#

503 Service Unavailable：服务暂时不可用#

504 Gateway Timeout：网关等待上游超时#

三、用户自检清单#

四、重试建议#

通常不建议无条件重试#

可以稍后重试#

五、说明#