API 接入常见错误排查

先查这五项

大多数接入失败可以先检查五项：API Key 是否完整、Base URL 是否正确、模型名是否存在、余额是否充足、工具是否自动拼接路径。不要一开始就跑高成本任务，先用短请求验证链路。

排障时要把“请求有没有到达平台”和“平台是否返回模型错误”分开看。控制台没有请求记录，通常说明 Base URL、网络代理、客户端路径或请求格式还没有打到平台；控制台有记录但失败，则再看模型名、余额、上下文长度和渠道状态。

公开咨询时不要贴真实密钥。建议准备四类非敏感信息：工具名称、请求时间、错误码或错误摘要、模型名。这样人工可以判断问题方向，同时不会暴露 API Key、后台链接或账号信息。

1. 401 或鉴权失败 检查密钥是否复制完整、是否填错位置、是否包含空格。
2. 404 或模型不存在 检查模型名是否在控制台可用，是否大小写或别名写错。
3. 429 或限流 降低并发，确认是否团队多人共用密钥。
4. 超时 缩短上下文或降低任务复杂度，先做连通性测试。

提交人工咨询时提供什么

请提供工具名称、模型名、非敏感错误码、出现时间、是否生产环境、预计调用量。不要提供真实 API Key、后台链接、账号密码、供应商信息或包含密钥的截图。

如果问题出现在团队项目里，请同时说明是否多人共用一个密钥、是否近期更改过模型名、是否增加了长上下文任务或图片任务。很多看似接口故障的问题，实际来自任务规模变化、并发变化或工具端配置变化。