How to collect feedback on 404 and 500 error pages

Why an error page is a feedback moment

A 404 or 500 page is the point where a visitor has no way forward. They followed a link that does not work, typed an address from memory, or hit a crash in the middle of a task. Most products show a message, a link to the home page and nothing else. The visitor leaves, and you never learn that the link in your newsletter points nowhere or that a button crashed the server.

The error page is also one of the few places where the visitor already knows something is wrong. That makes it a good place to ask for a report, as long as the request is short and does not pretend the problem is solved. Treat it as a bug entry point with a preselected type, not as a general feedback form.

Which error pages should carry the widget

Add the widget to the pages a person can reach without being signed in, and to the error pages in particular. A 404 page is served for any address that does not exist, so it is the best source of broken links. A 500 page is served when something fails on your side, so its reports are the most urgent. Make sure the error page loads the same widget script as the rest of the site, and that its origin is listed in the product's allowed origins, or the widget will not submit from it.

Do not add the widget to a maintenance page that loads nothing else. If the page is static HTML with no scripts at all, a plain link to your support address works better than a widget that cannot load.

How do you preselect the bug type on a 404?

Set data-trigger="none" on the script tag so the floating button stays hidden, then add a button with data-escuta-open="bug" in the error page markup. The widget opens with the bug type already selected. The visitor only has to describe what happened.

<h1>We could not find that page</h1>
<p>The link may be broken, or the page may have moved.</p>
<a href="/">Go to the home page</a>
<button data-escuta-open="bug">Report this broken link</button>

The button label matters more than the layout. "Report this broken link" tells the visitor that their report helps, and it sets the expectation that the report is about the link, not about their whole account. Avoid words like "contact support", because the visitor will expect a reply within minutes.

What metadata should an error report carry?

The widget saves the page URL with every item, so the broken address arrives for free. The URL is the most valuable field, because you can search for it later. Add two more values with setMetadata: the HTTP status and the referrer, which is the page the visitor came from. The referrer tells you which of your own pages or external sites send people to the dead link.

document.addEventListener("DOMContentLoaded", function () {
  if (!window.EscutaProduto) return;
  window.EscutaProduto.setMetadata({
    errorStatus: 404,
    referrer: document.referrer || null,
  });
});

Set the status in the markup of each error template, so a 500 page sends errorStatus: 500. Do not put user names, emails or session tokens in metadata for an error page. Addresses can carry personal data in query strings, so strip the query string if your URLs contain tokens or emails. Metadata is limited to 4 KB, which is plenty for these three values.

Can a 500 page collect feedback when the app is down?

Partly. If your 500 page is served by the same application that failed, the script and the button may not render. Serve the error page as static HTML from your CDN or hosting layer, with the widget script included, and the page works even when the application server is down. The widget script itself is served from escutaproduto.com and does not depend on your application.

If the widget still cannot load, the page should show a plain link to your status page or support address. A visible fallback is better than a button that does nothing.

How do you keep error reports from flooding the inbox?

A broken link that appears in a popular newsletter can produce dozens of reports in one hour. Two things keep this manageable. First, the widget is rate limited, so a single address cannot send a burst through the API, and the widget form has a hidden honeypot field against bots. Second, group the reports by their saved page URL. Copy the URLs into a spreadsheet and count them, so the most common broken path rises to the top.

When the same URL appears many times, fix the link once and reply to the group, not to each person. Use the per-product notification webhook if you want Slack or Discord to post each new report as it arrives.

Turning error page reports into fixes

Read the reports each morning, starting with the 500 pages. For each report, check the URL and the status. If the link is wrong, fix it or add a redirect. If the server failed, open the error in your logs and link the report in an internal note. Set the status to planned or in progress while you work, and to done when the fix is live.

If a visitor left an email address, reply once when the fix ships. The guide to following up on bug reports covers what to say. Keep the reply short and name the page they tried to reach.

Where the error page report lands in Escuta Produto

Create a product in the dashboard, copy its public key, and add the script with data-trigger="none" to your error templates. Add the site origin to the allowed origins so the widget can submit. Check the setup on a test URL that you know returns a 404, then send one report and confirm it arrives with the page URL and the status in metadata.

The widget docs list every option, including the preselected type attribute. For the rest of your site, the empty state guide describes a related moment where the page has no content but the visitor still has intent.