DeepSeek API 调用失败怎么办？错误排查、重试与备用模型切换

DeepSeek API 调用失败，先确认三件事：请求发给了谁、在哪一步失败、任务有没有可能已经执行成功。密钥、余额和参数错误应先修正；临时限流或服务端故障可以有限重试；仍未恢复，再切到已核实权限、任务兼容性和数据使用规则的备用路线。

这篇面向把 DeepSeek 接入应用或编程流程的开发者，提供最小诊断请求、错误处理表、Ofox 目录中的具体候选模型，以及可下载的 Python 切换示例。示例只处理短文本、非流式生成，不负责无缝迁移整个 Agent 会话，也不执行外部工具。

核验日期：2026 年 10 月 19 日。本轮核对了公开文档与 Ofox 模型目录，并通过 14 项本地合成测试。没有进行付费模型调用，也没有复现真实上游故障。目录中存在某个模型，不等于当前账号一定有调用权限，更不等于它能满足任务要求或在下一次故障中保持可用。本文由 Ofox 发布，文中包含 Ofox 的接入选项。

一、先判断是本地问题、账号问题，还是上游故障

先查看 DeepSeek 状态页，使用网关时还应查看实际网关的服务状态。状态页正常只是一个参考：某个区域、单个账号或者刚发生的问题，未必已经显示出来。

修改配置前，先留下一份足够定位问题的记录：

同一个小请求，在最小脚本中成功、在应用里失败，应重点检查应用的请求体、SDK、代理和超时设置。一个模型失败而另一个模型正常，可以缩小排查范围，但不能因此排除整个网关的问题：不同模型可能使用不同适配器和上游路线。

排查期间先控制新任务入队，避免定时任务不断叠加重试。上游恢复后，如果队列里堆满了重复请求，故障影响仍可能持续。保留原始任务 ID，恢复时按任务去重，而不是把所有失败记录再跑一遍。

二、根据错误类型决定下一步

下表前七类依据 DeepSeek 官方错误码文档。网关可能增加自己的错误码，也可能转换上游错误，因此要同时看 HTTP 状态与错误体。

截图采集于 2026 年 10 月 19 日，为官方英文参考文档，不是真实调用失败截图。

429 不一定等一会儿就好。有的平台会用它表示余额或硬性额度耗尽。下载示例会对已识别的额度错误码直接停止；接入生产应用前，还需按实际供应商文档补齐错误分类。超时也不等于没有产生 Token 消耗，它首先只是客户端观察到的现象。

DeepSeek 的限速与隔离文档说明了账号级并发限制。应统计共享同一账号的全部工作进程与密钥，而不是只降低当前这一个进程的速度。否则单机看起来已经降速，整个账号仍可能持续超限。

三、用一个最小请求定位问题

DeepSeek 官方直连接口当前使用的 Flash 模型 ID 是 deepseek-flash，其他网关不一定使用同一个名称。官方调用说明会说明当前映射。还未完成首次接入的读者，可以先看 DeepSeek API 配置指南。

使用可信终端，关闭 shell 命令追踪，通过已有密钥管理方式设置环境变量，并在空目录中执行下面的请求。它只发送一条合成文本，但可能按正常推理收费。不要在拥塞期间反复运行。

umask 077
curl --silent --show-error --fail-with-body \
  --connect-timeout 5 --max-time 45 \
  --dump-header response-headers.txt \
  --output response-body.json \
  --write-out 'HTTP %{http_code}; total %{time_total}s\n' \
  https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model":"deepseek-flash","messages":[{"role":"user","content":"Reply with exactly: DIAGNOSTIC_OK"}],"stream":false,"max_tokens":128,"thinking":{"type":"disabled"}}'

这里的连接超时 5 秒、总耗时上限 45 秒是本次诊断配置，不是 DeepSeek 的服务承诺。长推理任务可能需要另设时限。若 curl 不支持 --fail-with-body，先检查 curl --version。不要打开详细追踪后把带真实密钥的记录发给别人；在共享系统里，展开后的命令参数也可能被本机进程检查工具看到，更适合使用 SDK 与密钥管理器。

预期结果是 HTTP 200、完整且非空的答案包含 DIAGNOSTIC_OK，并保留返回的用量信息。还要看 choices[0].finish_reason：因长度上限结束的响应，不能按正常完成验收。失败时保留脱敏后的错误内容。再次执行会覆盖上面的两个文件，比较不同尝试时应使用不同目录。

最小请求成功后，逐项恢复真实功能：先增加历史消息，再启用推理、结构化输出、工具和流式响应。这样能发现是哪一项开始出错。不要为了测试连通性，把完整生产会话直接发送给新供应商。

四、备用路线到底换了什么

“切换备用”可能指三种不同动作，它们解决的问题不同。

同一供应商的两个 Key 可能共享额度；两个模型名可能指向同一部署；两个网关也可能调用同一个上游。能查到时，应记录实际服务供应商；路由不透明时，需要进一步核实。“URL 不一样”本身不能证明故障相互独立。

普通摘要、提取任务，可以评估另一款已验证的文本模型作为降级选择。代码修改要跑项目测试；图片理解要验证真实图片输入路径；工具型 Agent 则需保留系统指令、已完成的工具结果与待执行动作。不要把供应商专用推理字段原样复制给另一种协议。

如果备用平台的数据规则不符合业务要求，应让任务排队，或清楚告知用户暂时不可用。故障处理不能擅自扩大数据接收方。

五、在 Ofox 准备可核对的备用模型

10 月 19 日的 Ofox 公开模型目录列出了以下条目。这里验证的是目录信息，没有据此宣称实际推理成功，也没有比较模型优劣。

这些条目的目录均列出 OpenAI Chat Completions。两条 DeepSeek 记录的内置 web_search、web_fetch 能力标为 false，因此不能认为官方 Search/Fetch 能力与计费规则会跟随模型 ID 一起迁移。本文的备用示例只使用文本 Chat Completions，不调用供应商内置搜索。

具体准备步骤如下：

1. 打开当前模型详情，核对协议、模型 ID 与账号适用价格。本文不提供 Ofox 报价，也不承诺免费调用。
2. 确认符合需求后，注册 Ofox，在 API Keys 创建密钥，并按认证文档配置。Ofox Key 与 DeepSeek 官方 Key 属于不同账号体系。
3. OpenAI 兼容 SDK 的基础地址使用 https://api.ofox.ai/v1；直接发 HTTP 请求时再拼接一次 /chat/completions。检查是否误写了 /v1/v1，也不要向该路径发送 Anthropic 的消息结构。
4. 填入精确候选模型 ID，先跑无敏感数据的诊断任务，检查正文、用量及请求记录。若账号需要充值，先核对条款，再按自己的预算操作。
5. 完成下文的代表性任务与成本验收后，再把该路线加入生产故障切换。

如果主、备用都经过 Ofox，同一个网关仍是共同依赖。要覆盖网关自身故障，还需要一条经过批准的网关外路线。本轮没有证明这些候选之间的运行独立性，也不提供可用率保证。

六、先在本地验证重试与切换逻辑

下载 Python 示例与测试文件，解压到新目录。文件包括 failover.py、test_failover.py 与 README。进入目录后执行：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -m unittest -v

14 项本地测试注入合成响应并使用虚构密钥，不会发出 API 请求。覆盖主路线成功、503 后恢复、两次失败后切换、不可重试的 HTTP 错误、429 的额度与限流区别、次数耗尽、传输结果不明、显式允许重放、TLS 失败、200 响应不合格，以及数字和日期两种 Retry-After。

控制器最多尝试主路线两次、备用路线一次。在重试或换路线前遵守 Retry-After；如果要求等待超过示例的 30 秒预算，则停止，由调用方决定排队。没有有效等待指示时使用有上限的随机退避。代码禁用重定向，每条路线使用自己的密钥与模型。

准备真实调用时，通过已批准的密钥管理方式设置这些环境变量：

DEEPSEEK_API_KEY = 你的 DeepSeek 官方密钥
BACKUP_BASE_URL  = https://api.ofox.ai/v1
BACKUP_MODEL     = deepseek/deepseek-v4.1-flash-1017
BACKUP_API_KEY   = 你的 Ofox 密钥
BACKUP_DISABLE_THINKING = 1

对于这里的 DeepSeek 备用模型，BACKUP_DISABLE_THINKING=1 会显式关闭推理，适配短诊断回答。如果改用其他模型系列，应移除这个开关，按照该路线的文档配置推理与输出预算，不要自动转发 DeepSeek 专用字段。合成测试无法证明真实路线接受该参数，仍须单独核对。

随后执行 python failover.py。它会发送固定文本，并可能产生费用。结果包含所选路线、请求模型、返回模型、正文，以及存在时的用量和请求 ID。预期正文是 FALLBACK_TEST_OK，需要自行核对这一标记。主路线正常时，并不会实际运行备用路线；应按备用平台文档单独发送诊断请求来验证它，不要故意压垮或破坏主服务来触发切换。

遇到传输异常，示例默认停止，因为服务端可能已经接收请求。只有对这个固定的、没有外部操作的文本任务，才可通过 python failover.py --allow-ambiguous-replay 显式允许再次尝试。这个开关不适用于支付、发信、改文件或执行其他工具；即使只是生成文本，也可能产生两次费用。

示例直接使用 Requests，没有叠加 SDK 的自动状态码重试。迁移到 SDK 时，要关闭其自动重试，或把内部次数计入统一预算。每次尝试设置的 5 秒建连、30 秒读取无活动超时，不是整个请求的绝对耗时上限。生产接入还需要总时限、共享并发控制、持久化熔断状态与任务专用结果校验。

七、流式响应和工具执行要单独处理

答案已经展示给用户后，不应把另一个模型重新生成的开头接在原答案后面。应将第一条标为中断；重新生成时使用独立结果，并记录两次尝试。连接上的心跳或空行不一定是有效答案，除了连接活动，还应记录首段有效内容的等待时间。

工具调用要区分“模型提出动作”与“执行器完成动作”。模型返回工具调用，不代表操作已执行；执行器完成动作后网络中断，也不代表操作失败。为每个动作保存持久记录，包括任务 ID、动作参数或安全引用、执行状态与结果。恢复前先核对结果不明的动作。下游支持幂等机制时应正确使用，不能自造一个幂等请求头就假定对方会识别。

可以按这个顺序恢复：暂停新动作派发，确认已完成动作，取回保存的结果，核验待执行动作，再使用已批准模型继续。如果状态无法安全核对，停止并交由人工检查。下载示例刻意不包含工具执行器与流式解析器，不能直接拿来替代完整 Agent 恢复机制。

八、验收备用路线、核对成本，再恢复主路线

故障发生前准备一组代表性用例：日常任务、在支持范围内的较长输入、需要时的结构化输出，以及实际使用的每一种工具或图片操作。为每个用例定义正确结果。合法 JSON 仍可能填错值，代码能够编译也可能不符合业务要求。

每次记录实际路线、请求模型、返回模型（如有）、输入大小、参数、延迟、结束原因、用量、账单与通过情况。没有返回用量应记为未知，不能记为零费用。主路线的缓存命中不能直接继承到备用路线；对账时也要纳入失败与重试尝试。

明确降级策略：哪些任务允许切换、最多花多少、最多尝试几次、全部失败后怎么办。内部摘要也许能接受风格变化；财务提取或会修改代码的动作，可能需要额外复核。不要只因为另一模型返回更快，就悄悄把全部任务切过去。

持续失败时，应暂时停止向该路线发送正常流量，即打开熔断。冷却后先放少量探测；连续通过代表性检查，再逐步恢复。阈值应按业务时限与风险制定，不能把某篇教程里的数字当作通用标准。避免每失败一次就来回切换。恢复后保留备用配置，并记录故障开始、降级、探测和恢复的时间线。

仍需客服协助时，提交时间、脱敏后的状态码与错误码、请求模型、客户端版本、请求 ID 和最小合成复现，不附密钥、私人提示词或客户文件。客户端之间结果不同，可继续阅读 DeepSeek 跨客户端排查指南；通用状态码含义参见 API 错误码参考。

最终要验收的是：故障原因得到合理分类，重试次数确实受控，备用路线通过真实业务任务，并且恢复流程不会重复执行外部动作。查到一个模型、收到一次 HTTP 200，都只是其中一步。