← Voltar aos guias

LLM API常见报错排查：从401到限流的实战指南

先判断：错误来自哪里

LLM API 报错时，不要一看到失败就更换模型。先记录 HTTP 状态码、响应体、请求模型、请求耗时和 request ID。通常，4xx 是配置或请求内容有问题，5xx 多与服务端或上游模型暂时异常有关。把敏感的 API Key 脱敏后再保存日志，能显著缩短定位时间。

1. 401 或 403：认证信息没有真正生效

常见原因：Key 拼写错误、环境变量没有加载、请求头格式错误，或者把一个平台的 Key 发到了另一个平台。标准请求通常需要 Authorization: Bearer 加 API Key；使用 Claude 兼容接口时，也要按对应接口要求传递认证头。

排查方法：在启动时只打印 Key 的前四位和后四位，确认程序读取的是预期环境变量；检查是否误写成 Bearer加Key、Bearer:加Key，或把引号也放进了变量值。再用同一个 Key 发送一个最小请求，避免先排查复杂业务代码。403 则要进一步检查账户状态、模型权限和余额。

2. 404 或模型不存在：端点和模型 ID 不匹配

404 不一定代表服务不可用。常见陷阱是把 OpenAI SDK 的路径、Claude 原生路径和代理平台路径混用，或者复制了已经下线的模型名称。确认 SDK 的 base URL 设置为服务商要求的地址，不要在代码、环境变量和 SDK 初始化参数中重复拼接 /v1 或其他路径。模型名必须使用控制台或文档中列出的精确 ID，大小写和版本后缀都不能随意修改。

如果你通过 59API 调用 Claude 或 GPT，建议先从其可用模型列表选择 Opus、Sonnet、Haiku、Fable 或对应 GPT 模型，再用一个短 prompt 验证连通性。59API 的 API base URL 是 https://api.59api.com，并兼容 Claude Code、Codex 以及 OpenAI SDK；切换工具时，优先只改 base URL、Key 和 model 三项。

3. 400：请求格式或参数写错

400 通常发生在消息结构不符合接口规范，例如把 content 写成对象、role 使用了不支持的值、同时传入互斥参数，或把 max_tokens 写成字符串。不同兼容接口对 system 消息、工具调用、图片内容和 temperature 的支持并不完全相同。

• 先删除 tools、图片、JSON Schema 等高级字段，只保留 model、messages 和必要的 token 参数。
• 确认 messages 是数组，每条消息包含合法 role 与 content，并检查 JSON 是否能被本地解析。
• 逐个恢复可选参数；一旦复现，问题通常就在最后加入的字段。

4. 上下文过长：不是单纯提高输出上限

输入提示、历史对话、工具定义和预留输出空间会共同占用上下文窗口。出现 context length、maximum tokens 或类似错误时，先统计输入 token 数，再减少历史消息、压缩工具描述、截断检索结果，并为输出预留合理空间。不要盲目把 max_tokens 调到最大；输入已经超限时，增加输出上限没有帮助。

5. 429、超时与 5xx：做好限流和重试

429 可能表示请求频率过高、并发超限或余额不足。客户端应使用指数退避，例如等待 1、2、4、8 秒，并设置最大重试次数；不要对所有 4xx 无限重试。读取 Retry-After 时优先遵守服务端建议，同时限制并发量，避免重试风暴。

连接超时和 5xx 则应设置合理的连接及读取超时，记录每次重试原因，并使用幂等请求避免重复扣费。流式响应要持续读取数据，不能只等待一个完整 JSON；遇到中途断线时，可在业务允许的情况下重新发起请求。

6. 账单、额度和成本：把失败当成可观测指标

请求成功但返回额度不足、模型不可用或余额告警时，检查账户余额、单模型限额和项目级配额。对生产环境设置预算告警，并按模型、用户和状态码统计用量。若希望降低调用成本，59API 提供按量付费的 Claude 和 GPT 原生官方质量模型，价格定位较低，不需要为了省钱接受降级模型；同时还有推荐返利，具体规则以平台页面为准。

建议先用低成本模型完成连通性和参数测试，再在需要更强推理或更长上下文时切换模型。确认代码稳定后，可以注册 59API，使用 https://api.59api.com 配置现有 SDK，以较低的按量成本进行实际验证。