API 错误代码自查

在使用 API 过程中遇到报错，请先对照本手册查阅 HTTP 状态码 (Code) 或 错误信息 (Message)。

1. 客户端请求错误 (4xx)

此类错误通常由您的设置、参数或账户状态引起，请优先检查本地配置。

400 Bad Request (请求格式错误)

原因：JSON 格式不对、缺少必要字段（如忘了传 model）或使用了该模型不支持的参数（如 o1 系列模型不支持 system 消息）。

解决：检查代码语法或 IDE 设置。

401 Unauthorized (无效令牌)

原因：API Key (令牌) 填错了、被删除了，或者格式不正确（如多填了空格）。

解决：重新复制有效的令牌。

402 Payment Required (余额不足)

原因：账户额度已耗尽，或当前令牌的分组权限不足。

解决：请及时充值或检查额度。

403 Forbidden (权限/分组禁用)

原因：账号被系统封禁，或您使用的令牌所属分组被禁止访问该特定模型。

解决：联系管理员核实分组权限。

404 Not Found (接口地址错误)

原因：API Base URL 填写不规范。例如末尾多写或少写了 /v1。

解决：检查并修正接口调用地址。

413 Request Entity Too Large (请求过大)

原因：您输入的 Prompt（提示词）太长，超过了模型单次处理上限。

解决：缩减输入长度。

429 Too Many Requests (频率限制)

原因：您的请求发送太快，触发了上游账号的并发或速率限制。

解决：稍等几秒后重试，或降低请求频率。

2. 服务器与上游错误 (5xx)

此类错误通常表示服务器或 AI 供应商供应商暂时出现了问题。

500 Internal Server Error (内部错误)

原因：中转服务器或上游原厂（如 OpenAI）内部突发故障。

解决：稍后重试，通常几分钟内会恢复。

502 / 503 Service Unavailable (上游不可用)

原因：上游节点挂了、正在维护或服务器过载。

解决：这不是您的错。请联系管理员或切换到其他备用模型。

504 / 524 Gateway Timeout (请求超时)

原因：网络延迟过高，或 AI 思考时间太长，导致连接在规定时间内未完成。

解决：检查网络，或尝试更换响应速度更快的模型。

3. 模型名称报错 (Model Error)

报错：model_not_found (无可用渠道)

原因：

该模型在当前分组中未开启。

模型名称映射问题：有些 IDE 内置的模型名字（如 claude-4.6-opus）与平台实际接口名（如 claude-opus-4-6）不一致。

解决：请核对平台支持的模型列表，确保名称完全一致。

💡 站长提示：

如果您遇到的报错不在上述列表中，或者持续报 503/504 错误，请将 Request ID（请求 ID）截图反馈给客服，我们将为您查询具体链路问题。

API 错误代码自查

1. 客户端请求错误 (4xx)#

2. 服务器与上游错误 (5xx)#

3. 模型名称报错 (Model Error)#

💡 站长提示：#

1. 客户端请求错误 (4xx)

2. 服务器与上游错误 (5xx)

3. 模型名称报错 (Model Error)

💡 站长提示：