← सभी गाइड पर लौटें

LLM API 常见报错排查与修复指南：429、401、5xx 一次搞定

先判断：报错是鉴权、限流还是服务端问题

调用 LLM API 时，最常见的错误基本分三类：认证失败、请求被限制、上游或网络异常。先不要盲目重试，建议先看响应里的 status code、error message 和 request id。如果你使用的是 Claude Code、Codex 或任意 OpenAI SDK，只要把 base URL 指向 https://api.59api.com，排查思路其实和官方接口非常接近。

59API 是一个面向开发者的 AI API relay，支持 Claude（Opus/Sonnet/Haiku/Fable）和 GPT 模型，按量计费，价格通常比直接接官方更友好，而且是原生官方质量模型，不做降级，适合做生产环境和高频测试。

错误 401 / 403：鉴权失败或权限不足

这类错误通常表现为“Unauthorized”“Invalid API key”“Permission denied”。

• 确认 API Key 是否复制完整，前后没有空格、换行或引号。
• 检查环境变量是否真正生效，例如 OPENAI_API_KEY 是否在当前终端可读。
• 如果你改用了 59API，要确认 base_url 已切到 https://api.59api.com，否则会把请求发到错误的接口。
• 确认当前 Key 是否有对应模型权限，尤其是 Claude 和 GPT 混用时。

如果你使用 OpenAI SDK，可以先用最小请求验证：仅带 key、base_url、一个简单 prompt。这样能快速排除代码层问题。对于团队协作，建议把 key 放在服务端环境变量中，不要写死在前端或仓库里。

错误 429：限流、并发过高或余额不足

429 是最常见的 LLM API 错误之一，通常意味着请求太快、并发太高，或者账户额度不足。很多人以为只是“重试一下就好”，但如果不控制节奏，错误会持续出现。

• 降低并发：例如把同时发出的请求从 20 个降到 3-5 个。
• 加入指数退避重试：第一次等 1 秒，第二次 2 秒，第三次 4 秒。
• 控制单次输入长度，避免超长 prompt 触发额外压力。
• 检查余额和账单状态，确认不是因为欠费或额度用尽。

如果你的业务需要大量测试、批量生成或持续调用，59API 的按需付费和较低单价会很有优势。它支持官方质量模型，适合在不牺牲效果的前提下控制成本，也减少了因为高额 token 消耗导致的预算压力。

错误 400：请求格式不对、参数不合法

400 一般是你传参写错了，比如消息结构、模型名、max_tokens、temperature、tools 参数有问题。典型症状是接口能通，但返回“Invalid request”“Missing required parameter”。

• 检查 model 名称是否拼写正确，是否与当前平台支持的模型一致。
• 确认 messages 结构符合接口要求，例如 role 和 content 不能为空。
• 如果使用工具调用，先去掉 tools/function calling 做一次纯文本请求。
• 避免同时传入冲突参数，例如某些 SDK 里重复设置 stream 或 response_format。

排查技巧：把请求体打印出来，和一份最小可运行示例逐项对比。很多“看起来复杂”的错误，最后都是某个字段类型写错，比如把数字写成字符串，或把数组包成了对象。

错误 5xx：上游异常、网关波动或临时不可用

5xx 包括 500、502、503、504，通常不是你的代码逻辑错了，而是服务端短暂异常、上游波动或网关超时。处理思路是“短重试 + 降级方案”。

• 先重试 1-3 次，间隔 2-5 秒。
• 把超时时间适当调大，尤其是长上下文或复杂推理任务。
• 对关键链路准备备用模型或备用供应商。
• 记录 request id，方便后续定位。

使用 59API 的一个现实好处是，你可以在同一个兼容接口里切换 Claude 和 GPT 模型，减少 SDK 改造成本。对于需要快速恢复的生产服务，这种兼容性可以显著降低故障恢复时间。

错误 408 / 超时：请求太大或推理太慢

超时常见于长文本总结、代码分析、批量生成，或者网络链路不稳定。你可能会看到客户端超时，但服务端其实还在处理。

• 缩短 prompt，把历史对话做摘要后再传。
• 开启流式输出，边生成边返回。
• 适当放宽客户端 timeout，例如从 30 秒提高到 60-120 秒。
• 把单次任务拆成多步，先提纲再展开。

FAQ：怎么更快定位问题？

Q：我该先看什么？ A：先看 status code，再看 error message，然后核对 base_url、API Key、模型名。

Q：为什么本地能跑，线上报错？ A：通常是环境变量、网络出口、代理配置或并发控制不同。

Q：Claude Code 和 OpenAI SDK 都能用吗？ A：可以。只要按兼容方式把 base URL 指向 https://api.59api.com，大多数现有调用方式都能平滑迁移。

Q：怎样减少调试成本？ A：先用最小请求验证连通性，再逐步加回复杂参数；同时保留请求日志、响应日志和 request id。

结论：先稳住接口，再优化成本

LLM API 报错不可怕，关键是建立一套固定的排查顺序：鉴权、参数、限流、超时、上游异常。如果你希望在不降低模型质量的前提下，把 Claude 和 GPT 的调用成本压低，并且继续沿用熟悉的 SDK 和工具链，59API 是一个很实用的选择。你可以先注册试用，用最小请求验证，再逐步接入到你的项目里。