DEV Community

Error states that explain instead of blame: writing the "this link did not work" message

The first version of my downloader showed one message for every failure: Error. Try again.

It was honest in a narrow sense - something had gone wrong - but it told the visitor nothing useful. A deleted video, a private post, a provider outage and a mistyped link all looked the same, so every failure felt like the site was broken. People left. I do not blame them.

The problem was that my code knew much more than it was saying. The provider's response usually contained a reason, or at least a status code I could map to one. I just was not passing that reason along.

So I rebuilt the error handling in two places: the PHP endpoint that calls the provider, and the JavaScript that shows the message on the page.

Every error answers two questions

The rule I settled on is simple. Every error message has to answer two questions: what happened, and what you can do about it. "This link did not work" is the start, not the whole message. The second half depends on what we actually know.

  • A video that was deleted or made private gets: "This video is no longer available, or it is private. If you can open the link in your own app, check it is public, then try again."
  • A provider outage gets: "The video service is busy right now. This is on their side, not yours - please try again in a few minutes."
  • A pasted link from a platform I do not support gets: "I don't support this platform yet. TikTok, Instagram and Facebook links work here."

Explain instead of blame

Notice the difference in tone. None of those messages say the visitor did something wrong, because most of the time they did not.

A mistyped link is the one case where the visitor is involved, and even there I keep it neutral: "That link doesn't look like a video link. Check you copied the full address."

Blame is not only rude, it is bad information. The moment someone feels accused, they stop reading the part that tells them how to fix it.

Normalise errors in resolve.php

There is a technical habit behind this. My resolve endpoint, resolve.php, normalises three different providers' error JSON into one shape before the page ever sees it: a short code and a plain-words message.

The page never shows the provider's raw error. Partly that is for readability - nobody needs to see a provider's internal error string - and partly it is for safety. Raw provider responses sometimes contain URLs, keys or other detail that has no business reaching a visitor's screen.

I also stopped returning HTTP 200 for everything. When the provider says a video is gone, the endpoint answers 404. When the provider is down, it answers 502 or 503.

That matters less to the visitor than to me: when I read my own logs, the status code tells me at a glance whether the failure was a dead link or a dead provider, and I can count them separately. A site where every failure looks identical in the logs is a site where you cannot tell which problem to fix first.

Do not spin forever

One more thing I learned: do not show a spinner forever. If the provider does not answer within the timeout I set, the page says so plainly instead of spinning until the visitor gives up. An honest failure is better than a hopeful-looking one that never resolves. The visitor's time is the one resource I cannot give back.

None of this is complicated code. It is a few extra branches in the error handling and a bit of care with the words. But it changed how the tool feels to use. A failure that explains itself is a failure the visitor can act on, and a visitor who knows what to do next is a visitor who tries again instead of leaving.

I built the downloader this runs on at ramrom.io - a free, no-sign-up tool for saving TikTok, Instagram and Facebook videos. The error messages above are live on every page of it, and they are the reason most failed downloads now end with a second try rather than a closed tab.

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.