Browse documentation
Guides
Pause the affected exit IP, reduce extraction and caption request rates, then resume a single worker.
On this page
Pause, cool down, then test once
- Pause the affected IP. Stop all workers and immediate retries sharing that exit.
- Update nightly. Check the worker’s package and Deno during the pause.
- Allow a cooldown. Start with a few minutes; honor
Retry-Afterwhen supplied and wait longer if needed. - Test one source. Resume one paced worker only after the test succeeds.
- Replace the exit if necessary. Keep the lower request rate on the new IP too.
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version
deno --versionpython -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
--sleep-requests 3 --extractor-retries 1 --skip-download --write-info-json -P diagnostics \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Still getting 429? Wait longer or change the exit. Updating yt-dlp does not reset an existing IP rate limit; testing the full manifest only adds load.
Find the request being rate limited
| Failed work | Why it can generate many requests | First reduction |
|---|---|---|
| Video metadata / player requests | A full extraction can fetch several player responses and supporting resources. | One extraction per source; reuse its result inside the same job. |
| Search / channel / playlist enumeration | Large result sets require repeated continuation requests. | Bound the requested results, persist discovered IDs and avoid repeating the whole scan. |
| Transcript / caption tracks | Each requested language or translation can add a caption request. | Request only needed languages and add subtitle-specific sleep. |
| Media / fragments | Parallel videos and fragmented streams share the exit's request budget. | Reduce workers, fragment concurrency and external downloader connections. |
Read the hostname and the line immediately before 429. A timedtext/caption error should send you to subtitle pacing; a player request should send you to extraction pacing. Changing MP4 codecs or limiting media bytes does not slow a metadata-only loop.
If yt-dlp reports Sign in to confirm you’re not a bot, follow the bot-check guide. A flagged IP can stay blocked longer than a temporary rate limit. For a media 403, follow the separate 403 guide.
Use the right rate control
| Control | Scope | What it does not solve |
|---|---|---|
| --sleep-requests 3 | Delay between extraction requests within this downloader. | Coordination across other workers or all separate API calls in your application. |
| --sleep-subtitles 5 | Delay before each subtitle download. | A queue still requesting every available language across many workers. |
| --sleep-interval 5 --max-sleep-interval 10 | Randomized wait before media downloads. | A loop using download=False or --skip-download for metadata only. |
| --concurrent-fragments 1 | Native fragment concurrency within one media job. | The number of separate yt-dlp processes. |
| --limit-rate 2M | Media transfer bandwidth. | Search, player or transcript request frequency. |
| A shared per-exit queue | Total active jobs and request bursts through one exit IP. | An IP already being rate limited by unrelated tenants or jobs. |
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
--skip-download --write-subs --write-auto-subs --sub-langs "en.*" --sub-format "vtt/best" \
--sleep-requests 3 --sleep-subtitles 5 -P captions -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"The numbers above are starting settings for a controlled recovery, not published quotas. Increase spacing when rejection returns. Record the effective exit IP and worker count alongside errors so a newly started worker or a shared proxy does not quietly multiply the request rate.
Python example: pace metadata-only jobs
With download=False, media-download sleeps are not a job scheduler. Add a delay between sources as well as sleep_interval_requests inside yt-dlp. Start sequentially, stop a failing run and classify the error before deciding when to retry it.
import json
import random
import time
from pathlib import Path
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget
from yt_dlp.utils import DownloadError
sources = list(dict.fromkeys(
line.strip() for line in Path("urls.txt").read_text().splitlines()
if line.strip() and not line.lstrip().startswith("#")
))
options = {
"js_runtimes": {"deno": {}},
"impersonate": ImpersonateTarget(),
"noplaylist": True,
"sleep_interval_requests": 3,
"extractor_retries": 1,
}
with Path("metadata.jsonl").open("a", encoding="utf-8") as records:
for index, source in enumerate(sources):
if index:
time.sleep(random.uniform(5, 10))
try:
with YoutubeDL(options) as downloader:
info = downloader.extract_info(source, download=False)
except DownloadError:
# Do not immediately replay a failing queue. Inspect the error;
# cool down the exit before restarting after a rate limit.
raise
record = {key: info.get(key) for key in (
"id", "webpage_url", "title", "channel_id", "duration"
)}
records.write(json.dumps(record, ensure_ascii=False) + "\n")
records.flush()Do not detect every YouTube failure by searching for one error-message string and endlessly sleeping. Keep failed items with their error and attempt count. A shared cooldown belongs to the exit IP or session, while an unavailable video is an item-level failure. Other workers must respect the same cooldown.
Replace an exit that stays rate limited
On a direct connection, this means a different usable host/network egress. With a proxy, it means a different proxy exit, not merely a different gateway address. Stop the old workers before testing the replacement and keep the same low-load settings.
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
--proxy "http://USER:PASSWORD@HOST:PORT" --sleep-requests 3 --extractor-retries 1 \
--skip-download --write-info-json -P diagnostics \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"For a media job, keep that exit stable from extraction through transfer; rotate between jobs or before a fresh retry. A proxy pool helps distribute bulk work only when the pool's exits are usable and the per-exit rate is controlled. If the replacement immediately hits 429 too, inspect shared usage and the queue rather than accelerating rotation.
Resume without repeating completed work
- Retest the exact failing operation: metadata, search page, caption track or media stream.
- Start one worker and observe several items. Restore concurrency gradually, with a per-IP limit.
- Reuse discovered IDs and existing metadata instead of repeating every search and extraction.
- Keep requested caption languages explicit and retry only missing tracks.
- Use bounded retries with increasing waits and jitter in the shared queue. Stop retrying immediately when the same exit is rejected again.
Maintain separate media and caption states. If the MP4 completed but captions got 429, keep the file and schedule a caption repair. Redownloading the media adds load and still does not establish text completeness. A media archive alone is not a record of caption coverage.