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

大模型接口报错速修：从鉴权失败到流式中断的排查指南

先花一分钟，判断问题出在哪里

遇到大模型接口报错，先别换模型或反复重试。记录状态码、错误类型、请求标识、模型名和耗时，再用同一密钥发送一条只有“回复：收到”的短请求。如果短请求成功，优先检查原请求的长度、工具参数或并发；如果也失败，再查鉴权、地址和账户状态。日志中务必隐藏密钥及敏感提示词。

鉴权失败：先查密钥，再查权限

• 401：确认使用目标平台签发的密钥，排除复制时带入空格、换行，以及环境变量未加载。更新密钥后，重启仍持有旧配置的进程。
• 403：查看响应中的具体原因，检查模型权限、账户限制或来源地址限制。不要把所有权限错误都归因于余额，也不要将密钥提交到代码仓库。

路径或模型不存在：别把协议混着用

404 或模型不存在通常需要检查请求地址、接口路径与模型标识。59API 的基础地址是 https://api.59api.com；OpenAI 兼容客户端通常还涉及 /v1 前缀，具体配置以平台文档为准，避免客户端自动追加后形成重复路径。

模型标识应从控制台或可用模型列表复制，不要凭展示名称猜测。使用 Claude Code、Codex 或 OpenAI SDK 时，也要确认各自所需的协议和配置项；兼容工具不等于所有端点都能互换。

参数错误或上下文超限：缩小到最小请求

遇到400、422，或请求体过大的 413，先读错误字段，再暂时移除工具调用、结构化输出和可选参数，仅保留模型与一条用户消息。成功后逐项加回，定位不兼容字段。

上下文预算包含输入、历史消息、工具结果及预留输出，不能只数当前问题。优先删减重复历史、截断冗长工具结果，并调低输出上限；同时检查所选模型支持的参数名称与取值范围。

限流与服务故障：重试必须有边界

• 429：区分请求速率、令牌速率与额度不足。限速时降低并发、使用队列；额度不足则检查余额或账单，盲目重试无效。
• 500、502、503、504：可能来自模型服务、中转网关或网络链路。保留请求标识，检查平台状态，并对可恢复故障做有限重试。

若响应提供 Retry-After，优先遵守；否则可采用带随机抖动的指数退避，例如约一秒、两秒、四秒，最多重试三次。检查 SDK 是否已自动重试，避免多层叠加。超时不代表服务端没执行，重复请求可能增加费用；工具调用还应设计业务去重。

超时或流式中断：检查整条连接链路

分别设置连接超时和读取超时，并检查反向代理、负载均衡器的空闲超时。流式接口返回成功状态后仍可能中断，不能只看最初的状态码；应持续检查事件中的错误，并确认收到协议规定的结束信号。

不要对每个网络分片直接解析完整 JSON，应先按流式协议组装事件。连接断开后，不要把重新生成的内容直接拼接到旧文本后面，否则可能重复输出。排查证书问题时，也不要用关闭证书校验作为长期修复。

用低成本环境完成验证

排错阶段使用短输入、低输出上限和单并发，确认链路正常后再压测。59API 提供低价按量计费的 Claude、GPT 官方原生模型接入，不做模型降级，并兼容 Claude Code、Codex 与 OpenAI SDK，适合降低集成和验证成本。实际模型价格、可用性与推荐返佣规则以控制台为准。

如果正准备搭建测试环境，可以注册 59API，先跑通一个最小请求，再逐步迁移真实业务流量。

मूल्य · दस्तावेज़