yt-dlp HTTP 429 错误怎么办？原因与解决方法

在使用 yt-dlp 批量下载 YouTube 视频、备份内容或做跨平台运营时，有时会遇到报错 HTTP Error 429: Too Many Requests。

429 表示目标服务认为当前请求超出了允许的访问频率或使用限制。

限制可能与出口 IP、账号状态、请求方式或特定接口有关，具体原因需要结合报错阶段判断。

要解决这个问题，关键在于先判断 429 出现在哪个请求阶段，再对症处理。

yt-dlp HTTP 429 错误是什么？常见原因有哪些

429 是目标服务返回的「请求过多」状态码。它通常不是单次请求触发的，而是同一出口 IP 在一段时间内累积的请求被判定为过度使用。

常见原因可以归纳为下面几类：

需要注意的是，429 不等于「IP 被永久封禁」。它多数情况下是软性限制，调整请求方式或切换出口后可以恢复。

yt-dlp HTTP 429 错误怎么解决

建议按下面的顺序排查。先做成本最低、最直接的检查，再逐步调整请求方式。

1. 先判断 429 出现在哪个请求阶段

yt-dlp 下载 YouTube 视频时，并不是只发一个请求，而是会依次请求视频网页、初始数据、播放器接口、视频流和字幕等。不同阶段报 429，排查方向并不一样：

先根据日志确认 429 发生在哪一步，比直接换 IP 更有效。

2. 暂停请求，避免持续重试

收到 429 后继续高频重试，可能让访问受限的时间进一步延长。先暂停当前任务，留出一段时间，再检查下面的项目。如果只是偶发，恢复后通常可以继续。

3. 更新 yt-dlp，检查运行环境

旧版本可能包含已经失效的提取逻辑。先升级到最新版本，并确认 JavaScript 运行环境可用。

YouTube 提取过程中可能需要运行 JavaScript 挑战求解脚本，yt-dlp 官方推荐使用 Deno，也支持通过配置启用 Node 或 QuickJS。

如果日志出现 JavaScript Runtime 或 EJS 相关警告，应检查运行环境和挑战求解组件是否正常。

如果升级后仍出现 429，可以继续检查请求频率、出口 IP、Cookie 状态及具体报错接口。

4. 调整请求间隔

yt-dlp 默认请求间隔较短，批量任务可能在短时间内产生大量请求。可以用下面的参数拉开间隔：

yt-dlp \
  --sleep-requests 2 \
  --sleep-interval 5 \
  --max-sleep-interval 15 \
  --batch-file urls.txt

其中 --sleep-requests 控制提取视频信息时各个请求之间的等待时间，--sleep-interval 与 --max-sleep-interval 控制每次下载开始前的随机等待范围。

两者针对的是不同的等待阶段，配合使用可以降低短时间内的请求密度。

5. 使用 Cookie 处理登录与验证

429 有时伴随验证要求。官方建议：如果浏览器访问 YouTube 时出现 CAPTCHA，先在浏览器里完成验证，再把浏览器 Cookie 传给 yt-dlp：

yt-dlp --cookies-from-browser chrome "视频URL"

需要注意：Cookie 可以帮助 yt-dlp 使用浏览器中的登录状态，或通过必要的访问验证，但不保证解决所有 429 问题。

使用个人账号进行高频自动化请求时，也应注意账号和访问限制风险，不要将 Cookie 文件分享给他人。

若浏览器与 yt-dlp 使用不同的网络出口，可通过 --source-address 绑定本机发起连接时使用的源 IP 地址（适用于设备有多个可用网络出口的情况），保持验证环境一致。

6. 检查 IPv4 / IPv6 网络连接

如果确定是网络路由或连接层面的异常，可以尝试指定协议栈：

yt-dlp --force-ipv4 "视频URL"

这只用于排查 IPv6 路由或连接异常的情况，不能把 IPv6 等同于高风险 IP。多数 429 问题与协议栈无关，先确认其它步骤更有效。

7. 检查字幕及其他接口请求

如果日志显示 429 出现在字幕下载阶段，应重点检查字幕接口的请求情况，包括请求频率、字幕语言和客户端状态。

若只有某一种字幕下载失败，可以单独测试其他可用语言，判断问题是否集中在特定字幕请求上。

如果完成以上检查后仍然受限，再考虑更换出口 IP。

另外，若出现 403、LOGIN_REQUIRED 或格式不可用等报错，可能涉及 PO Token 或客户端配置问题，与 429 是两回事，应单独排查。

如何通过代理 IP 降低 yt-dlp 的 429 错误

当单一出口 IP 反复受限，或需要长期运行批量任务时，可以通过代理 IP 分散请求压力。

1. 命令行配置代理

通过 --proxy 参数接入 HTTP 或 SOCKS5 代理：

# SOCKS5 代理
yt-dlp --proxy "socks5://username:password@proxy_host:port" "视频URL"

# HTTP 代理
yt-dlp --proxy "http://username:password@proxy_host:port" "视频URL"

代理可与请求间隔参数组合使用，例如：

yt-dlp --proxy "socks5://username:password@proxy_host:port" \
       --sleep-requests 2 \
       --batch-file urls.txt

2. 在配置文件中写入默认代理

为避免每次重复输入，可以把代理写入 yt-dlp 配置文件：

▸ Windows：%APPDATA%\yt-dlp\config 或 config.txt

▸ Linux / macOS：~/.config/yt-dlp/config 或 config.txt

如果使用便携版，也可以将 yt-dlp.conf 放在 yt-dlp 可执行文件所在目录。

在配置文件中加入：

--proxy "socks5://username:password@proxy_host:port"
--sleep-interval 3
--max-sleep-interval 10

3. 动态住宅代理与静态住宅代理怎么选

两种代理都能提供住宅网络归属的出口，但适用场景不同：

选择时要注意：轮换周期应根据任务量、请求频率和服务商配置调整，不要一味追求高频切换。

动态住宅代理适合在不同视频任务之间分配出口，而需要连续下载的视频任务应优先考虑粘性会话，避免下载过程中频繁更换出口，否则可能造成连接中断。

此外，静态 IP 不代表不会触发 429，动态 IP 也不代表每次轮换都能恢复访问。

4. 产品选择

如果需要长期运行 yt-dlp 批量采集任务，可以考虑配置住宅代理 IP。

IPDEEP 提供动态住宅代理和静态住宅代理，支持 HTTP、HTTPS 和 SOCKS5 协议，可根据任务规模、目标地区及会话需求选择合适的代理类型。

通过合理分配出口 IP 和控制请求频率，有助于降低单一网络出口的请求压力。

常见问题

Q1：yt-dlp 触发 429 后，多久能恢复？

HTTP 429 的限制时间由目标平台决定，可能在一段时间后自动解除。如果持续重试，可能进一步延长受限时间。

建议暂停请求，检查网络出口和访问状态，再逐步恢复任务。

Q2：批量下载播放列表时，如何配置比较稳妥？

建议组合「住宅代理 + 随机延迟 + 失败重试」，例如：

yt-dlp --proxy "socks5://your-proxy-endpoint" \
       --sleep-requests 2 \
       --sleep-interval 5 \
       --max-sleep-interval 15 \
       --batch-file urls.txt

请求间隔用于控制下载节奏，失败重试用于应对偶发网络波动，两者配合可以兼顾稳定性和效率。