错误码与限流

接口返回的 HTTP 状态码遵循通用语义。下表列出常见状态码的含义与处理建议，更详细的排查步骤见错误与故障排查。

状态码	含义	常见原因	建议
200 OK	请求成功	正常返回数据	—
400 Bad Request	请求参数错误	提示词过长、模型名称错误、传参格式有误、缺少必填参数	校验模型名与请求体格式后重新发送
401 Unauthorized	密钥认证失败	API Key 输错、含多余空格、已过期重置，或密钥与接口地址不匹配	检查 Authorization: Bearer 请求头与 Base URL
402 Payment Required	余额不足	密钥有效，但账户余额不足或免费额度已耗尽	到控制台查看余额并充值，或更换有效密钥
403 Forbidden	访问被禁止	账号风控封禁、IP 被拉黑，或密钥没有对应模型的调用权限	检查账户状态与密钥的模型授权范围
404 Not Found	接口地址错误	访问路径不存在，或模型名已下线	确认 Base URL 中 /v1 只出现一次，并使用当前可用的模型名
429 Too Many Requests	请求频率过高	触发平台限流	降低并发、增大请求间隔，并使用退避重试
500 Internal Server Error	服务商内部故障	上游异常，与本地配置无关	稍后重试
502 / 503	服务宕机 / 暂时不可用	平台维护，接口暂时无法连通	查看控制台公告与服务状态，稍后重试

重试建议

请不要对所有错误无限重试：

• 401、402 及参数错误（400）属于配置或额度问题，应先修正配置、补充额度，盲目重试无效。
• 429 与 5xx 属于限流或服务端临时问题，可使用退避重试（如 1s、2s、4s 逐步拉长）。