错误码 400
描述：请求参数不正确。解决方法：
请根据返回的错误信息提示，检查并调整请求参数格式、字段名称或取值范围，确保请求体符合 API 接口文档规范。
错误码 401
描述：API Key 鉴权失败，通常是密钥未设置、格式错误或已失效。常见子类：
- 未传入 API Key：请求头缺少
Authorization，或未按Authorization: Bearer {API 密钥}的格式传入。 - API Key 格式错误：密钥应以
sk_开头，检查是否被截断、混入空格或换行。 - API Key 已删除或失效：密钥在控制台被删除后立即失效，使用它的调用都会返回 401。请改用有效的密钥。
- 环境变量未正确读取：如通过环境变量或配置文件传入，确认变量已设置且被正确加载。密钥的设置与排查参见管理 API 密钥。
- 检查是否传入了正确的 API Key；
- 确保 API Key 是最新有效的；
- 如使用环境变量或配置文件，请确认调用时已正确读取，排查方法参见管理 API 密钥。
错误码 403
描述：权限不足。可能是账户没有调用该模型的权限，也可能是该 API Key 的模型访问范围不包含目标模型。常见子类：
- 账户权限不足：当前 API Key 所绑定账户不具备调用该模型的权限。
- 未完成实名认证：某些模型要求实名认证后才能使用。
- 密钥模型访问被限制（错误码
model_access_denied）：该 API Key 配置了「模型访问」，目标模型不在其可访问范围内。此时请联系团队管理员调整该密钥的模型访问设置，详见管理 API 密钥 — 模型访问。
- 请确认当前 API Key 所绑定账户是否具备调用该模型的权限；
- 如返回错误码
model_access_denied，说明该密钥的模型访问范围不包含目标模型，请联系团队管理员在模型访问设置中放开该模型； - 某些模型可能要求通过实名认证后才能使用：
- 登录控制台查看账户的实名认证状态；
- 若当前账户未实名，请先完成实名认证；
- 如有其他已实名账户，请使用其下 API Key 发起请求。
错误码 429
描述：触发了 Rate Limit（调用频率限制）。解决方法：
- 根据错误信息，区分是 TPM（每分钟 Token 限制）还是 RPM（每分钟请求次数）被触发；
- 可参考平台的 Rate Limits 文档；
- 如需提升速率限制，请联系支持申请调整或使用认证账户发起请求。
错误码 503 / 504
描述：服务端超时或不可用，通常与系统负载或流控有关。原因归因：
- 模型服务所在节点负载过高（GPU / CPU）；
- 非流式请求生成时间过长，超过网关（Nginx / API Gateway）的 timeout 配置；
- 下游依赖服务（如 Redis、模型引擎）不可用；
- 限流组件触发高峰保护策略，返回 503。
解决方法：
用户侧建议：- 增加重试机制：建议使用指数退避策略，避免短时间内重复压测；
- 改为流式请求：Streaming 模式可边生成边返回 token，减少整体延迟，有效降低长文本生成失败率；
- 优化调用配置：如通过自建代理调用，请确保
client_timeout与proxy_timeout不低于 60 秒； - 错峰调用：如遇高并发场景，可稍后再尝试或避开高峰时段。
- 加强模型服务的负载监控与自动扩容机制；
- 网关层设置更合理的
proxy_read_timeout； - 设计更精细的限流规则（如优先级队列、核心业务优先保活）；
- 搭配 Prometheus + Alertmanager 配置 503/504 异常告警。
错误码 500
描述：服务器内部错误，通常为后端服务异常或模型引擎崩溃。解决方法：
- 该类问题通常无法由用户自行解决，建议联系平台支持团队排查后端日志与资源状态；
- 同时可尝试更换请求模型或降级服务重试。
- 首先参考 API 返回中的
message字段； - 然后查看控制台或日志的调用轨迹；
- 最终，如问题持续存在，请提交工单或联系技术支持获取帮助。