When a download fails on my site, the visitor sees one of two honest sentences: "This video looks deleted or private" or "Our provider is having a bad day — try again in a few minutes." Getting to that split took more work than I expected, because a failed request looks exactly the same from the outside either way.
The problem is that the site does not talk to TikTok, Instagram or Facebook directly. It talks to a provider API, and that API talks to the platforms. So when something goes wrong, there are two completely different causes hiding behind the same blank result: the video itself is gone, or the middleman is down. A visitor cannot tell the difference, and if the message does not tell them either, they paste the same link five times and assume the site is broken.
The first thing I had to learn is that each provider reports these two failures in its own dialect. One returns a 404 with a JSON body saying the media was not found. Another returns a 200 with an empty media array and no error field at all.…