Getting Started

Common Errors

roubleshoot the most common issues quickly

Updated December 17, 2025

Before you start (fast checklist)

Copy the error code shown in the UI (usually ERR-...).
If the error happened after clicking a button, open DevTools → Network, click the failed request, and copy:
- Status code (401/403/404/429/5xx)
- Response JSON (look for error and code)
- Response header X-Error-Code (if present)
Note the time it happened and what you were doing (start crawl, export, etc.).

If you still need help, open a prefilled support ticket at /support/new and include the above.

Error codes (what they mean)

`ERR-...` (in the UI)

What it is: a reference ID generated by the app UI to help support correlate the incident.
What to do: copy it and include it in your support message.

`X-Error-Code` (in the API response headers)

What it is: a server-generated error code added to unexpected 5xx responses (and sometimes other failures).
Where to find it: DevTools → Network → failed request → Headers.
What to do: include it in your support ticket; it’s the best correlation handle for server-side logs.

Authentication & permissions

“Unauthorized” (401)

Common causes

Your session expired.
You’re signed out in another tab/device.

Fix

Refresh the page.
Sign out and sign back in.
If it repeats, clear site cookies for this domain and sign back in.

“Access denied” / “Forbidden” (403)

Common causes

You don’t have access to that resource (ownership/role).
Bot protection blocked the request (sensitive endpoints).
CSRF validation failed (state-changing request).
Your account requires verification.

Fix

Confirm you’re using the correct account (check top-right profile/email).
Retry the action once (refresh first).
If you see this during payments, crawls, account changes, AI, disable aggressive privacy extensions for the site and retry.
If the message says your account requires verification, complete verification and retry.

“CSRF validation failed” (403)

Common causes

Open tab for a long time, then attempted a sensitive action.
Multiple tabs with a stale CSRF token.

Fix

Hard refresh the page and retry.
Close duplicate tabs of the app and retry.

Rate limiting & abuse protection

“Too Many Requests” (429)

Common causes

Rapid clicking / repeated retries.
Automation or scripts polling too frequently.
Bulk operations (exports, crawls, AI) triggered too quickly.

Fix

Wait 30–60 seconds and try again.
Avoid repeated retries; use a single retry.
If you’re polling status, slow down your polling interval.

Crawl issues

Crawl fails immediately / only discovers one broken URL

Common causes

Web Application Firewall (Cloudflare/Sucuri/AWS WAF) blocking the crawler.
Bot protection (bot fight mode / challenge pages).
robots.txt disallowing the crawler.
Server rate limiting or geo-blocking.

Fix

Check https://yourdomain.com/robots.txt and ensure our crawler isn’t blocked.
If you use a WAF/bot protection:
- Allow our crawler User-Agent: LinkHealthBot/1.0
- Temporarily disable strict bot challenges for your domain, then re-run a crawl.
Re-run the crawl after changing settings.

Many 429s on external links

What it means

The target sites rate limited our requests (common for large crawls).

Fix

Treat as “may be false positive” unless it’s your own domain.
Re-run later; compare results across crawls to confirm.

Timeouts / “Gateway Timeout” (504) or slow pages

Common causes

Your site is slow to respond (TTFB/edge).
Your server blocks or throttles crawlers.

Fix

Re-run a crawl.
Improve page performance and verify your server/CDN isn’t throttling our crawler.

Exports & reports

Export fails (PDF/CSV)

Common causes

Large export + network interruption.
Temporary server issue.

Fix

Retry once.
Narrow filters to reduce export size (e.g. export just Broken Links).
If it repeats, open support and include the X-Error-Code from the export request.