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
errorandcode) - 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.txtdisallowing the crawler.- Server rate limiting or geo-blocking.
Fix
- Check
https://yourdomain.com/robots.txtand 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.
- Allow our crawler User-Agent:
- 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-Codefrom the export request.
Billing & Stripe
Checkout fails / can’t open billing portal
Common causes
- Ad blockers or strict privacy settings interfering with Stripe redirects.
- Temporary Stripe network issue.
Fix
- Disable extensions for this site (ad blockers / tracking protection), retry.
- Try an incognito window.
- If it repeats, open support with time +
X-Error-Code.
API (Agency / API v1)
“API key required” / “Invalid API key” (401)
Fix
- Provide your key via
Authorization: Bearer <key>orX-API-Key. - Ensure you’re using the correct key and it hasn’t been revoked.
“API access requires an active Agency subscription” (403)
Fix
- Confirm the account has an active Agency subscription.
“Missing scope” / scope-related 403s
Fix
- Create a key with the required scopes for the endpoint (read vs write).
- Use the correct key for the operation.
When to contact support
Contact support if:
- You see repeated 5xx errors (server issues).
- You are blocked by 403 and the steps above don’t resolve it.
- Crawls consistently fail after WAF/robots changes.
Include
- UI error code (
ERR-...) if shown - Network error details (status code + response body)
X-Error-Codeheader if present- Exact steps to reproduce
- Domain and crawl reference (if applicable)