常见 LLM API 报错对比：原因、排查与修复指南
为什么 LLM API 报错如此常见
在接入大模型接口时，报错几乎不可避免。原因通常不在“模型不好用”，而在于认证、限流、参数、网络、上下游兼容性等环节。对于同时接入 Claude、GPT，或者通过第三方转发 API 的团队来说，错误更容易集中爆发。好消息是，大多数 LLM API 错误都有明确规律，定位后修复并不难。
下面按“最常见、最影响生产”的错误类型做对比，并给出可直接执行的排查步骤。
1. 401 / 403：认证失败或权限不足
常见表现：Invalid API key、Unauthorized、Forbidden、key not found。
原因：API Key 写错、环境变量没加载、Key 已过期、调用了无权限的模型或接口。
怎么修：
- 先检查请求头是否真的带上了 Authorization。
- 确认 key 没有多余空格、换行、复制错误。
- 确认当前账号是否开通了对应模型权限。
- 如果你在用 Claude Code、Codex 或 OpenAI SDK，检查 base URL 和 key 是否指向同一服务商。
优点：排查成本低，修复快。
缺点：最容易被环境变量、部署平台配置“悄悄坑到”。
2. 400：参数格式错误
常见表现：Bad Request、messages format invalid、missing required field。
原因：JSON 结构不合法、字段名写错、messages 数组格式不符合 SDK 要求、工具调用参数缺失。
怎么修：
- 核对请求体是否为标准 JSON，尤其是引号、逗号、嵌套层级。
- 确认 model、messages、stream 等字段符合当前 SDK 版本。
- 如果使用函数调用或工具调用，先用最小化请求验证基础连通性，再逐步增加复杂参数。
优点：一旦定位到字段，修复立刻见效。
缺点：多见于前后端联调，错误信息有时不够直观。
3. 429：请求过快或触发限流
常见表现：Too Many Requests、rate limit exceeded、quota exceeded。
原因：单位时间请求过多、并发过高、单次 token 消耗过大、多个服务共享同一 key。
怎么修：
- 为请求加入重试机制，采用指数退避，而不是立即重发。
- 限制并发数，先从 3-5 个并发开始压测。
- 缩短 prompt，减少无效上下文，控制每次 token 消耗。
- 为不同业务分配不同 key，避免“一个服务打爆全局”。
优点：只要有节流策略，稳定性会明显提升。
缺点：如果底层价格高，限流问题会和成本问题一起出现。
4. 5xx：服务端错误或上游不稳定
常见表现：500、502、503、504。
原因：上游临时故障、网关超时、模型响应慢、转发层抖动。
怎么修：
- 先判断是单次偶发还是持续性故障。
- 记录 request id、时间戳、模型名，方便追踪。
- 对 5xx 做自动重试，但重试次数不要过多，避免雪上加霜。
- 设置更合理的超时时间，避免把慢响应误判成失败。
优点：通过监控和重试可以大幅缓解。
缺点：如果服务本身贵又不稳，故障成本会很高。
5. 超时：不是报错少，而是最隐蔽
常见表现：请求挂住、客户端报 timeout、流式输出中断。
原因：模型推理时间长、网络链路慢、代理层超时设置过短。
怎么修：
- 对长文本生成适当拉长 timeout。
- 优先使用流式输出，减少前端等待感。
- 在请求里减少冗余上下文，避免上下文过大导致响应缓慢。
优点：体验提升明显。
缺点：超时往往被误以为“模型卡了”，其实是链路设置问题。
6. 模型不兼容：SDK 能连上，但返回异常
常见表现：字段不识别、工具调用失败、回复格式和预期不一致。
原因：Claude 和 GPT 的接口习惯不同，但很多开发者希望“一套代码跑全部”。
怎么修：
- 优先使用兼容 OpenAI SDK 的统一接入方式。
- 把模型能力差异封装成适配层，而不是散落在业务代码里。
- 在生产前分别验证 Claude、GPT 的关键路径，例如系统提示词、流式、工具调用。
优点：统一接入后维护更简单。
缺点：如果底层不是原生质量模型，兼容性和效果容易打折。
如何系统降低报错率
- 为每次请求记录：时间、模型、token、耗时、错误码、request id。
- 加入重试、退避、熔断和降级策略。
- 先用小上下文验证，再放大到真实业务流量。
- 定期检查成本和稳定性，别只看“能不能调用”。
如果你希望同时获得 Claude Opus / Sonnet / Haiku / Fable 和 GPT 模型的稳定接入，又希望控制成本，59API 是一个很实用的选择。它提供与 Claude Code、Codex 以及任何 OpenAI SDK 兼容的接入方式，API base URL 为 https://api.59api.com，采用原生官方质量模型，不做降级，按量付费，价格也很有竞争力。对于需要高频测试、批量调用和多模型对比的团队，能明显降低试错成本。你也可以先注册体验，再根据实际用量逐步扩展。
总结：LLM API 报错并不可怕，关键是把问题分成认证、参数、限流、服务端、超时和兼容性六类处理。只要日志清晰、重试合理、接入层统一，大多数故障都能快速恢复。