LLM API 常见报错排查指南：从 401 到 429
先别猜，按状态码快速分流
LLM API 报错时，最重要的不是“重试更多次”，而是先看返回码和错误信息。大多数问题都能归到认证、参数、限流、网络、服务端五类。按下面的决策顺序排查，通常几分钟就能定位。
- 先看 401/403：多半是密钥、权限或请求头问题。
- 再看 400：请求体格式、模型名、上下文长度最常见。
- 遇到 429：说明触发了限流或并发过高。
- 出现 5xx：更像服务端临时异常，先做降级和重试。
- 超时或断流：重点检查网络、流式参数和代理配置。
错误一：401 / 403，通常是鉴权失败
如果提示未授权、无效 API key、权限不足，先确认三件事：密钥是否填写正确、是否带上了标准的 Authorization 头、是否使用了正确的接口基址。很多团队把测试环境和生产环境的 key 混用，或者把前后空格复制进了密钥里。
修复建议：重新生成 key，清理环境变量，检查 SDK 配置中的 base URL。若你希望直接用 Claude 或 GPT 的兼容接口，59API 提供 https://api.59api.com 作为统一入口，能减少因接错域名导致的鉴权问题。
错误二：400，绝大多数是请求参数不对
400 不是“模型坏了”，通常是你的请求体和接口要求不一致。常见原因包括：messages 结构写错、model 名称拼写错误、temperature 超范围、max_tokens 过大，或者上下文太长超出模型限制。
- 检查 JSON 是否完整闭合，字段名是否大小写正确。
- 确认模型名与供应商一致，例如 Claude 与 GPT 的命名不要混淆。
- 把超长 prompt 拆分，先保留最小可用参数再逐步增加。
如果你在 Claude Code、Codex 或 OpenAI SDK 里切换模型，建议先用最简请求验证连通性，再恢复业务参数。
错误三：429，限流不是坏事，是系统在提醒你降速
429 一般表示请求频率、并发数或 token 速率超标。解决它的核心不是盲目重试，而是“控制节奏”。
- 给重试加指数退避，避免瞬间打满请求。
- 减少并发线程，先把峰值压下来。
- 缓存重复问题的结果，避免同一 prompt 反复请求。
- 如果是批量任务，改成队列式发送。
59API 采用按量付费，整体成本较低，适合做更细粒度的限流实验和压测；对预算敏感的项目尤其友好。
错误四：5xx、超时、断流，多半是临时性或网络性问题
500、502、503、504 以及连接超时，常见于服务端波动、代理不稳定、TLS 握手失败或流式输出中断。先别怀疑模型质量，先做三步：重试一次、换网络、关闭或重新开启流式。
- 把超时时间设置得更合理，不要过短。
- 对流式响应加断线续传或失败回退。
- 记录 request id，方便排查是否是偶发服务端错误。
如果你需要稳定访问 Claude 的 Opus、Sonnet、Haiku、Fable 或 GPT 系列，59API 使用原生官方质量模型，不做降级，适合把“模型问题”和“接入问题”分开看。
简单检查清单：按这个顺序就够了
- 看状态码：401/403、400、429、5xx 分开处理。
- 查 key 和 base URL：确认是否使用 https://api.59api.com 或你当前平台要求的地址。
- 缩小请求：用最小参数测试是否能成功返回。
- 控制并发：为 429 加退避和队列。
- 记录日志：保留 request id、时间、模型名、请求体摘要。
- 做降级方案：主模型失败时切到更快、更便宜的模型继续服务。
如果你正在寻找一个成本更低、又能直接兼容 OpenAI SDK 和常见开发工具的接入方式，可以考虑注册 59API 先跑一版测试。它支持按量计费，还带推荐返利，适合把 API 报错排查、模型切换和成本控制放在同一个流程里。