Telling "video deleted or private" apart from "provider is down" — and saying so plainly

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. A third returns a generic "something went wrong" string for both cases, and the only clue is a numeric code buried two levels deep. So the work is not in the error message — it is in the mapping table I keep in resolve.php, one branch per provider, turning each provider's version of "gone" and each version of "down" into the same two internal states.

The second thing is the timeout. A provider that is down does not always say so. Sometimes it just never answers, and PHP sits there waiting. I cap provider calls at a short timeout, because a slow API is worse than a failed one — it hangs the whole page. A timeout is not proof the video is gone, so it lands in the "provider is down" bucket every time. That rule alone stopped the most unfair outcome: telling someone their video was deleted when it was actually fine and the API had just gone quiet.

The third thing is checking the easy answer first. Before I spend an API call, the page validates the pasted link itself: is it a supported platform, is it a real URL, does it look like a video link at all? A mistyped link gets its own message before anything reaches the provider. That sounds trivial, but it cut a whole class of "deleted video" reports that were really just a link copied with a missing character.

The wording matters as much as the logic. "Video not found" is accurate but cold, and it leaves the visitor wondering whether to try again. "This video looks deleted or private" says what happened and, just as importantly, that trying again will not help. "Our provider is having a bad day" is deliberately informal — it says the fault is on my side, not theirs, and that waiting a few minutes is the right move. I never show raw provider errors. A visitor should not have to read a JSON blob to work out whose fault it is.

I also log which bucket each failure fell into, without storing the link or anything about the visitor. That log is how I know whether a spike in failures is a provider outage or a wave of deleted videos. The distinction is useful on my side of the fence too: one means I wait and retry, the other means there is nothing to fix.

The lesson, for a small tool site like ramrom.io, is that an error message is a feature, not an afterthought. A visitor who is told plainly why something failed trusts the tool more than a visitor who got a spinner and a shrug — and they come back the next time they need a download.