DeepSeek API 常见报错与限流排查：401、404、429、超时（2026）

DeepSeek API 的报错大致分四类：鉴权、路径与模型名、限流、超时。正确的排查顺序是：先看 HTTP 状态码和错误类型，再看请求 ID 和最小复现，最后才改提示词或换模型。顺序反了，很容易把配置问题当成模型能力问题。

本文按 401、404、429、超时四类拆开，给出原因、排查步骤和可复用的退避代码。模型与价格以站内模型价格为准。

说明：DeepSeek 是其权利人的商标。错误类型、限流口径和接口行为可能随版本调整，本文以 2026 年 10 月的常见情况为例，最终以官方文档为准。

一、四类错误先分清

状态或现象	常见含义	典型原因	处理顺序
401	鉴权失败	Key 错误、Bearer 缺失、Key 失效	先修凭证
404	路径或模型不存在	Base URL 错误、模型名旧、路径重复拼接	查地址和模型名
429	限流或配额受限	并发突增、共享 Key、重试风暴	退避、降并发
超时	连接或读取超时	网络、长输出、推理模型、代理	分层排查
400	请求参数或上下文有问题	上下文超限、格式错误	量化后拆分
5xx	上游服务错误	服务端故障或过载	退避、换通道

日志里至少记录时间、状态码、错误类型、模型名、耗时和请求 ID。不要记录完整 Key，也不要把用户原文整段打印到日志。

二、401：先查请求头，再查 Key

401 表示身份没有通过验证，和模型能力、余额通常无关。按下面顺序排查：

请求头是否使用 Authorization: Bearer <key>，而不是其他鉴权方式。
Key 前后是否有空格、换行或多余引号。从聊天窗口复制最容易带进来。
环境变量是否真的加载，可以只打印前缀确认。
Key 是否被删除、轮换或停用。
Base URL 和 Key 是否属于同一平台，官方 Key 配网关地址会 401。
反向代理是否覆盖或丢弃了 Authorization 头。

export DEEPSEEK_API_KEY="sk-你的密钥"

curl "https://api.deepseek.com/chat/completions" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "max_tokens": 16
  }'

这条命令返回 200，说明 Key、Base URL 和模型名三项都通。仍然 401 时，换一把新 Key 做最小请求，区分是 Key 本身的问题，还是代理或网关配置的问题。

三、404：地址和模型名最容易错

404 通常不是“接口挂了”，而是请求打到了不存在的路径或模型。常见原因：

Base URL 写成了别的厂商地址，或者多写、少写了 /v1。
SDK 会自动拼接 /chat/completions，手写路径时又拼了一次。
模型名使用了已下线的旧版本，或大小写、后缀不一致。
网关地址和官方地址混用，路径规则不同。
反向代理重写规则把路径改坏。

排查时先用 curl 打完整地址，确认返回体里的错误信息；再把 Base URL 和模型名逐项对照站内价格页。不要在代码里硬编码多个地址，按环境配置，避免测试环境的地址带到生产。

四、429：限流不是余额不足

429 表示请求超过了速率、并发或配额限制。DeepSeek 在高峰期可能对请求进行限流或排队，具体口径以官方文档为准。常见触发场景：

多个服务共用一把 Key，互相挤占额度。
批量任务在整点同时启动，形成流量脉冲。
重试没有退避，越失败越发，形成重试风暴。
长输出或推理任务占用资源较多，留给并发的空间变小。

现象	可能原因	处理
高峰期集中 429	上游负载或流量脉冲	排队、平滑发送、错峰
单 Key 多服务 429	配额被共享	按项目拆 Key
重试后更严重	无退避重试	指数退避加随机抖动
长请求先 429	输出 Token 占用高	降 max_tokens 或并发

import random
import time
from openai import OpenAI, RateLimitError, APITimeoutError, APIStatusError

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://api.deepseek.com",
    max_retries=0,  # 关掉 SDK 自动重试，避免和自定义重试叠加
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="deepseek-chat",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
                timeout=60,
            )
            return resp.choices[0].message.content
        except (RateLimitError, APITimeoutError):
            wait = min(2 ** attempt, 20) + random.random()
            print(f"第 {attempt + 1} 次失败，等待 {wait:.1f} 秒")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("重试次数已用完")

print(ask("用一句话解释什么是限流"))

重试只适合瞬时错误。已经产生副作用的业务，先用幂等键或状态检查确认是否执行过，再决定要不要重发。

五、超时：先分清连接、读取和流式

超时不等于服务不可用，要先定位卡在哪一段：

现象	可能原因	处理
连接超时	DNS、网络出口、代理不可达	检查网络和代理，换线路
首 Token 很慢	上游排队、提示词过长	缩短输入、错峰、换轻量模型
读取超时	输出太长、推理模型思考久	提高读取超时、限制输出
流式中断	网络抖动、代理断流	支持断线重连、记录已收内容
全站同时超时	本地出口或上游故障	切备用通道、看服务状态

import httpx
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://api.deepseek.com",
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
)

连接超时和读取超时要分开设置。把所有超时设成一个很大的值，故障时会拖住线程池；设得太小，又会把正常的长任务误杀。按任务类型分别配置，是更稳妥的做法。

六、一张排查顺序表

记录状态码、错误类型、请求 ID、模型名和发生时间。
401 查 Key、请求头、环境变量和平台是否匹配。
404 查 Base URL、路径拼接和模型名。
400 查参数、上下文长度、图片或文件格式。
429 查并发、共享 Key、重试策略和高峰时段。
超时查 DNS、代理、输出长度和读取超时设置。
5xx 先退避重试，持续出现再联系服务方并附请求 ID。
每次故障后补监控和告警，不要等用户反馈才发现。

七、监控与日志

字段	用途
时间与项目	定位高峰和影响范围
状态码与错误类型	区分鉴权、限流、上游错误
请求 ID	找服务方排查的关键凭证
模型名与版本	判断是否换模型后出现
输入输出 Token	分析成本和长请求
耗时与重试次数	发现尾延迟和重试风暴

监控至少按小时统计 401、404、429、超时和 5xx 的数量。错误率突增时先看是否集中在某个项目、某把 Key 或某个模型，再决定降并发、切通道还是回滚版本。

常见问题

429 是余额不足吗？

不是。429 表示请求超过了速率、并发或配额限制，余额不足通常会返回其他错误或在响应体中说明。先查并发和共享 Key，再查账户余额。

404 最常见的原因是什么？

Base URL 错误、路径重复拼接和模型名过期。先用 curl 打完整地址，再对照站内价格页确认模型名，通常几分钟内能定位。

超时要不要无限重试？

不要。重试要有上限、退避和告警，超时还可能意味着请求已经在上游执行。有副作用的业务先确认状态，再决定是否重发。

流式输出中断怎么办？

先记录已接收的内容和中断位置，再判断是网络抖动、代理断流还是上游超时。客户端要支持重连和去重，不要直接把半截内容当完整结果入库。

网关报错和官方报错怎么区分？

保留请求 ID 和错误类型，用同一条请求分别打官方入口和网关入口。能快速区分是 Key、网络、网关配置还是上游服务的问题。

下一步

先在中商起航 AI 网关创建测试 Key，把 401、404、429 和超时各演练一次，再接入生产监控。模型可用性与价格以模型价格为准。