← Volver a las guías

LLM API 常见错误排查：从 401 到超时的实用修复指南

调用大语言模型 API 时，报错不一定意味着模型不可用。多数问题来自密钥、请求格式、额度或网络配置。与其反复重试，不如先记录 HTTP 状态码和响应正文，再按下面的步骤逐项检查。排查时不要把 API 密钥贴到公开日志或代码仓库中。

401 或 403：先检查密钥和权限

常见原因：密钥为空、复制时带入空格、密钥已撤销，或者请求发到了与该密钥不匹配的服务。检查环境变量是否正确加载，并确认请求头格式为 Authorization: Bearer YOUR_API_KEY。在 Claude 原生接口中，认证头可能使用 x-api-key，应按对应接口文档设置，不要混用。

如果密钥有效仍收到 403，查看响应正文和账户状态，确认服务权限、余额或使用限制。切勿将密钥硬编码进前端网页；应放在服务器环境变量中。

404：确认 API 地址和模型名称

404 经常是路径拼错或模型名不受当前服务支持。使用兼容 OpenAI 的接口时，核对完整请求路径，例如聊天补全接口；如果通过 59API 接入，基础地址是 https://api.59api.com，不要漏掉 SDK 所需的具体路径。模型名称也要与服务商当前提供的列表完全一致，注意大小写、连字符以及版本后缀。

还要确认客户端没有自动追加重复路径。例如，某些 SDK 会自行补上 /v1；若你填写的 base URL 已包含它，最终地址就可能不正确。

400：检查 JSON 和参数组合

400 通常表示请求内容无效。先检查 JSON 是否语法正确，再核对模型支持的字段。常见问题包括消息缺少 role 或 content、把数字写成字符串、设置了不支持的参数，或同时使用互斥选项。逐步删减参数，保留模型名和一条简单用户消息，确认基础请求成功后再加回功能。

多模态请求还要检查图片或音频的数据格式与大小限制。不要默认所有模型都支持相同输入类型。

429：降低请求速率并检查额度

429 表示请求过快，或账户触发了用量、并发限制。查看响应头和错误正文，区分速率限制与余额不足。遇到临时限流时，采用指数退避：例如等待 1、2、4 秒后重试，并加入随机延迟；同时限制并发数、为重复任务做缓存。不要在循环中立即无限重试，否则只会加重限流。

超时或 5xx：设置合理重试策略

网关超时和 5xx 可能是网络波动、服务繁忙，也可能是生成内容较长。适当提高客户端超时，尤其是长文本任务；对可安全重试的请求使用有限次数的退避重试，并记录请求 ID、耗时和状态码。若请求已经提交但客户端超时，不要盲目重复执行可能产生费用的任务，先确认服务是否支持查询或幂等处理。

流式输出异常：按事件逐段读取

启用流式响应后，返回内容通常由多个事件组成，不是一个完整 JSON。使用支持流式读取的 SDK，逐段解析数据，并处理结束标记、连接中断和不完整事件。排查时可先关闭流式模式，确认普通请求正常，再恢复流式处理。

用更简单的方式管理模型接入

如果你需要在 Claude 与 GPT 模型之间切换，59API 提供按量付费的中转接入，兼容 Claude Code、Codex 和 OpenAI SDK，基础地址为 https://api.59api.com。平台提供 Claude Opus、Sonnet、Haiku、Fable 等选项及 GPT 模型；按平台介绍，使用原生官方品质模型，不做降级，并提供推荐返利。成本敏感的开发者可以先从小额调用开始，核对模型、费用和错误日志，再逐步上线。

如果你希望用较低成本测试多个模型，可以注册 59API，先用一条最小请求验证密钥、地址和模型配置，再接入现有项目。

Precios · Docs