第一次调用失败后，该去哪里求助

第一次调用 API 就报错，很容易让人怀疑是不是自己哪里做错了。其实大多数失败都能通过一套固定的排查路径解决，剩下的再带着关键信息求助，效率会高很多。

先确认失败发生在哪一层

调用链路上任何一环出问题，都会表现为「调用失败」。先分类，再对症处理：

• 网络层：请求根本没发出去，或超时、连接被重置。
• 认证层：HTTP 401/403，通常和 API key 有关。
• 请求格式层：HTTP 400，参数不符合接口要求。
• 配额与余额层：HTTP 402 或提示余额不足、额度耗尽。
• 服务端层：HTTP 5xx，或返回了上游模型提供方的错误信息。

看到状态码先别慌，它已经告诉你该往哪个方向查。

自助排查清单

1. 检查 API key 与认证头

• key 是否完整复制，有没有多余空格或换行。
• 请求头是否按文档要求携带，例如 Authorization: Bearer <key>。
• key 是否被禁用、删除或超过了有效期。
• 如果你用的是 OpenAI 兼容 SDK，确认 base_url 指向的是聚合站的接口地址，而不是官方地址。

2. 检查请求体格式

• 模型名是否写对，注意大小写和命名风格（比如带不带厂商前缀）。
• messages 结构是否符合规范，角色名是否用了支持的值。
• 是否传了目标模型不支持的参数（不同模型对参数支持范围不同）。
• JSON 是否合法，有没有尾随逗号或未转义字符。

3. 检查账户余额与计费

• 账户是否有足够余额。聚合站通常按官方价乘以一个系数扣费，余额不足会直接拒绝请求。
• 如果你同时贡献了 key，注意贡献返利和消费扣费是两条独立的账。
• 确认当前使用的 key 属于哪个账户，避免误用测试账号。

4. 检查网络与超时

• 本地网络是否能正常访问该域名，可先用简单的连通性命令测试。
• 是不是流式响应中途断开，可尝试先关闭流式对比。
• 超时设置是否过短，长回复容易被客户端主动切断。

5. 缩小问题范围

• 换一个最简单的请求（比如只发一句「你好」）再试。
• 换一个模型再试，判断是模型特有问题还是全局问题。
• 换一个客户端（curl、官方 SDK、第三方工具）再试，排除封装库的干扰。

常见错误对照

• 401/403：key 无效、格式错误、权限不足。
• 400：参数错误、模型名不存在、请求体不合法。
• 402/余额提示：余额不足或额度用尽。
• 404：接口路径或模型名写错。
• 429：请求过于频繁，或触发了上游的速率限制。
• 5xx：上游服务或聚合站临时故障，通常稍后重试即可。

求助前该准备什么

带着完整信息提问，能让对方更快定位问题。建议整理以下内容：

• 请求时间：精确到分钟，最好带时区。
• 使用的模型名：原样复制，不要凭记忆写。
• 完整的错误信息：包括 HTTP 状态码和返回体中的 error 字段，不要只截取一句话。
• 最小可复现请求：去掉业务无关内容后仍能触发错误的那段请求，注意脱敏。
• 调用方式：用什么 SDK、什么语言、什么客户端版本。
• 已尝试的排查步骤：说明你已经排除了哪些可能，避免重复劳动。
• 是否稳定复现：每次都失败，还是偶发。

切记：不要直接粘贴完整的 API key。如果确实需要提供，先替换成占位符，或只保留前后几位用于核对。

去哪里求助

• 官方文档与状态页：先看有没有已知故障公告或常见问题说明。
• 站内工单或支持渠道：适合涉及账户、余额、key 状态等只有服务方能看到的信息。
• 社区群组或论坛：适合通用问题，也容易搜到别人遇到过的同类错误。
• 上游模型提供方的文档：当错误信息明显来自上游时，对照其参数和限制说明。

提问的写法

一个好的提问通常包含三部分：我做了什么 → 期望什么 → 实际发生了什么。附上最小复现请求和完整错误信息，比「用不了」「报错了」有用得多。

如果问题涉及余额或计费，说明你的账户类型和最近的调用情况，但依然不要泄露 key。

把排查变成习惯

第一次失败是正常的。把上面这套清单存下来，之后遇到类似问题可以直接对照。多数错误在认证、格式、余额这三类里，剩下的交给日志和最小复现请求，基本都能说清楚。