Home›Guides›Limits

What this downloader cannot do

Every limit and all six failure codes, read from the code that serves this site. Last reviewed 2026-11-02.

Most pages about a downloader list what it does. This one lists what it refuses, what it returns when it refuses, and the two things it does not limit even though competitors imply they do. Everything here is read from the server, not estimated.

Two limits that are not there

No maximum file size and no maximum length. Both are worth stating outright because nearly every tool in this category implies a cap, and people reasonably assume one exists.

The download path never checks a total. It streams in 256 KB chunks and writes each one straight to your browser. A 500 MB video takes the same code path as a 5 MB one. Nothing here stops it and nothing here shrinks it — there is no transcoding step at all.

Failure codes return HTTP 200, and that will break clients

A lookup that fails after reaching the handler answers HTTP 200 with {"ok": false, "code": "..."}. Only rate limiting (429) and an unhandled exception (500) produce a different status. Branch on ok, not on the status line.

The two endpoints behave differently and that is worth knowing before you write anything: the lookup endpoint answers 200 for nearly every failure, while the download endpoint returns honest 4xx and 5xx codes, including a plain-text 400 when a host is not on the allowlist.

The 12 limits

Each row names the constant behind it, so you can check rather than trust.

1Video lookups per address — 20 per minuterateLimit.resolve_per_min = 20 in server.py. Counted per client address in process memory, fixed one-minute window that restarts at the first request.
2Downloads per address — 15 per minuterateLimit.download_per_min = 15. Separate counter from lookups — spending your lookups does not block a download whose link you already have.
3Contact form messages — 3 per minuterateLimit.contact_per_min = 3. Exceeding it redirects back to the contact page with err=rate rather than returning JSON, because that form is a plain HTML post.
4Lookups you can repeat for free — 30 minutescache.resolve_ttl = 1800 (RESOLVE_CACHE_TTL). A repeat lookup of the same post inside this window makes no upstream request at all and returns cached: true. So the 20-per-minute figure only applies to posts you have not just looked up.
5Posts held in that cache — 800cache.resolve_max = 800 (RESOLVE_CACHE_MAX), floor of 50. When full, the oldest quarter is dropped — not a strict LRU, so a very busy server can evict a post younger than 30 minutes.
6Parsing sources tried — 3, in orderSOURCES = [fxtwitter, vxtwitter, syndication]. Tried in that order; the first one that returns a post with video wins. Each failure waits 0.3 s before the next.
7Pause between source attempts — 0.3 secondstime.sleep(0.3) in the resolve loop. Three sources therefore add at most about 0.9 s of deliberate delay to a lookup that fails.
8Download attempts per file — 3for attempt in range(3) in the download handler. Backoff is 0.6 s, then 1.2 s, then give up with code busy and HTTP 502.
9Time to reach the CDN — 30 secondsurlopen(..., timeout=30) in the download path. Per attempt, so a dead CDN can take up to three of these before the transfer is refused.
10Maximum video size — noneThere is no byte ceiling anywhere in the download path — the file is streamed through in 256 KB chunks with no total check. The only practical limit is the source file itself. Stated plainly because every competing tool implies a cap.
11Maximum video duration — noneNo duration check exists. A 40-minute video downloads exactly like a 4-second one, subject only to the rate limit above.
12Hosts a download may come from — 3video.twimg.com, ton.twimg.com, pbs.twimg.com. Anything else is refused with a plain-text 400 'host not allowed' before a connection is opened, so the download endpoint cannot be pointed at an arbitrary server.

All 6 failure codes

The second column is the HTTP status you actually get. Four of the six are 200 — that is not a typo.

1not_supported · HTTP 200 · Yours · retry: NoThe link is not a recognisable X post URL, or it resolved to a post that no source could read. Covers a profile link, a search URL, a typo in the status id, and a t.co shortlink that no longer expands. Returned inside a 200 body, so read ok before reading code.
2no_video · HTTP 200 · X's · retry: NoThe post was read successfully and genuinely has no video. This is deliberately separated from not_supported: at least one source returned the post, and it confirmed there was nothing to download. A post that is text, or images only, ends up here.
3generic · HTTP 200 · Ours · retry: YesEvery source failed for a reason that was not 'this post has no video' — usually a network error or a source being down. Worth retrying, because the next attempt may reach a different source.
4empty · HTTP 200 · Yours · retry: NoThe request carried no url field at all, or it was blank after trimming. A client bug rather than a bad link, which is why it is not folded into not_supported.
5busy · HTTP 429 or 502 · Ours · retry: LaterTwo different situations share this one code, and the status separates them: HTTP 429 means you hit the per-address budget (20 lookups or 15 downloads a minute); HTTP 502 means the CDN could not be reached after three attempts. Wait in the first case, retry shortly in the second.
6bad_event · HTTP 400 · Yours · retry: NoThe analytics endpoint received an event name it does not accept. Only the four names the page itself sends are valid. Nothing user-facing depends on this endpoint, so seeing it in a log usually means a bot is poking at it.
Retrying, in one sentence: retry generic, and busy only when it came with a 502. Everything else answers the same way on the tenth attempt.

Checked against the live server, 2 November 2026

Every code above was triggered for real on that date, from a single address on the server itself, with a new one-minute window for each burst. Nothing below is inferred from the source. The point of publishing the run is that you can repeat it: send the same request and compare the status line and the body.

What we sent, and what came back
RequestHTTPBody
Lookup with no url field200{"ok": false, "code": "empty"}
Lookup of a profile link (x.com/NASA), sent 21 times in one minute200 ×20, then 429not_supported ×20, then busy
Lookup of a text-only post (jack/status/20)200{"ok": false, "code": "no_video"}, answered in 1.2 s
Lookup of a status id no source could read (i/status/1)200{"ok": false, "code": "generic"}, answered in 1.0 s
Download whose URL is on example.com, sent 16 times in one minute400 ×15, then 429plain text host not allowed ×15, then busy
Download of an allowlisted host with a path that does not exist502{"ok": false, "code": "busy"} after 3.7 s (three attempts)
Analytics event with an unknown name400{"ok": false, "code": "bad_event"}
Same post looked up three times200"cached": true each time, 42 ms → 7 ms → 4 ms
The 429 carries no Retry-After header. The response had only Date and Content-Type. Since the window is a fixed minute counted from your first request, the workable rule for a client is: on 429, wait until the minute rolls over, then retry. Do not poll in a tight loop — every attempt, including one you know will be refused, is counted.
Refused requests still spend the budget. In the download burst above, fifteen requests were rejected with a plain-text 400 for an off-allowlist host, and the sixteenth was refused with 429. A client that hammers a bad URL locks itself out of the downloads it actually needs. Validate the host before you call the endpoint.

What it deliberately does not do

1It does not produce MP3, GIF or any audio-only fileThe output is MP4, always. X serves video as video; there is no audio track endpoint being called here. If you need MP3 or GIF, that conversion happens after download, in another program. Saying this plainly matters because search results for 'twitter video to mp3' are full of tools that quietly hand back an MP4.
2It does not upscale, or offer a quality the post does not haveThe quality list is the list of variants X actually serves for that post. A 480p post will not offer 1080p, and no file is ever re-encoded. If the picker shows one option, that is the only rendition in existence.
3It does not sign in to X, and cannot fetch protected postsEvery read is anonymous. Private, protected, age-restricted and deleted posts all fail — that is the correct answer, not a bug waiting to be fixed.
4It does not store the videoFiles are relayed from the CDN to your browser as they arrive, in 256 KB chunks, with no copy written to disk on the server. There is nothing to expire because nothing is kept.

What is stored, and for how long

1The video itselfNever written to disk. Streamed from X's CDN straight to your browser in 256 KB chunks.
2Lookup resultsHeld in memory for 30 minutes so a repeat lookup costs no upstream request, then gone. Not written to any file.
3Request logOne line per lookup and per download, with no IP address and no account — there are no accounts. Rotated when the file passes 2 MB.

Questions this page gets asked

Does a failed lookup return an HTTP error code

Usually not. A lookup that reaches the handler and then fails answers HTTP 200 with {"ok": false, "code": "..."} in the body — not_supported, no_video, generic and empty all arrive that way. The exceptions are rate limiting (429) and an unhandled exception (500). Read ok first; checking the status alone will make most failures look like successes.

What is the difference between not_supported and no_video

no_video means a source read the post and confirmed there is no video in it. not_supported means no source could read the post at all. The distinction matters because the first is a final answer about the content, while the second may be a temporary failure of ours.

Is there a maximum file size

No. The download path streams the file through in 256 KB chunks and never checks a total. A 500 MB video goes through the same code as a 5 MB one. Nothing here will stop it, and nothing here will shrink it either.

Is there a maximum video length

No. There is no duration check anywhere in the server. The only ceiling you can actually hit is the 15-downloads-per-minute budget, which is about how many times you ask, not how big the answer is.

Why did the same link work a minute ago and fail now

Because parsing depends on third-party sources. Three are tried in order, and any of them can be down or rate-limiting us at a given moment. A link stored in the 30-minute cache will keep working; one that was never cached depends on those sources answering.

Does looking up the same link twice cost two requests

No. The second lookup inside 30 minutes is served from memory with cached: true and makes no upstream request. It also does not touch the reliability of the answer — a cache hit returns exactly what the first lookup returned, including a failure if the first one failed. Failures are never cached.

Why is the download link a list of URLs joined by a pipe

Because a post can have several renditions, and the handler takes them as ordered fallbacks: it tries the first, and if the CDN refuses it moves to the next. All of them must be on video.twimg.com, ton.twimg.com or pbs.twimg.com — anything else is refused before a connection opens, which is what stops this endpoint from being used to fetch arbitrary URLs.

Can it download a video from a protected account

No. Reads are anonymous and there is no login path, so a protected post is unreachable. That is stated as a limit rather than a bug.

Does it work for posts with several videos

Yes. Each video in the post gets its own set of quality options and its own download, rather than the tool picking one for you.

What does cached: true mean

That this particular lookup made no request to X or to any third-party source; the answer came from a copy held in memory from a lookup within the last 30 minutes. It is not a claim that the video still exists — only that we did not ask again.

Is the video re-encoded or watermarked

Neither. The bytes that leave the CDN are the bytes your browser receives. No transcoding step exists in this server, so quality is exactly what the post offers and no watermark is added.

Can I use the downloaded video however I like

Downloading does not transfer any rights. The file is still the copyright holder's. This tool only moves bytes you could already see in a browser; what you do with them is a separate question with a separate answer.

Checking any of this yourself

Send the lookup endpoint a profile link instead of a post link. The status line will say 200 and the body will say not_supported. Send it the same post link twice and watch the second response carry cached: true. Those two tests tell you whether a client is reading this API the way it was written.