Troubleshooting

Start here

Open the site in a normal browser window (headless and automated browsers are ignored: navigator.webdriver switches the tracker off, and bot user agents are dropped on the server).
Network tab: look for POST …/v1/e.
Turn on debugging: add data-debug to the script tag or init({ debug: true }), then inspect window.__x3 in the console.
Ask Claude: the MCP tool setup_verify_installation checks snippet, key, proxy, CSP and recent events for a URL (MCP tools). The dashboard's prompt "Fehlersuche" (MCP prompt /mcp__x3__debug_tracking) walks Claude Code through status, website check, code and a live test visit (Claude Code prompts).
Settings → Setup-Status lists every open item with a reason code and its fix (reason codes, e.g. origin_rejected).

Status codes of POST /v1/e

Status	Meaning	Fix
204	Accepted (or silently dropped: bot, quota, budget)	–
400	Malformed batch, unknown/invalid key format	Check that `data-key` is a `pk_3x_` key
403	Revoked key, origin not allowed, or an invalid proxy key	Add the origin under Settings → Tracking → Allowed origins; `http://localhost` needs Allow localhost; check `X3_PROXY_KEY`
413	Batch larger than 16 KB	Should not happen with the SDK; custom senders must split
429	More than 60 batches per minute from one IP	Load tests: use several IPs or a test project

No requests at all

The page is in an iframe – the SDK only runs in the top window.
The browser opted out: open the site once with ?x3_notrack=0.
require consent mode and no consent yet.
An ad blocker blocks the API host → use the first-party proxy.
CSP blocks the script or the connection → CSP.
The path is excluded (/api, /_next, the proxy path, or the project's excludePaths).

Data arrives, but …

All visitors look like one person / sessions are merged. The API sees your proxy's or CDN's IP instead of the visitor's. Use the provided proxy recipes (they forward the IP with a proxy key) or set X3_TRUSTED_IP_HEADERS correctly on a self-hosted API (Environment). The dashboard shows a warning when more than 30 % of a day's sessions share one hash.

Custom events are missing. Check the event catalog: unregistered names beyond 200 per project are dropped; blocked events are dropped; string props that are not identifier-like are removed and a required prop missing drops the event. POST /v1/events/validate tells you why.

Everything is "direct". The referrer is stripped by Referrer-Policy: no-referrer on the linking site, or links use rel="noreferrer". Use UTM parameters on links you control.

SPA navigations are missing. The router does not use the History API: set hashRouting or call x3("page", path) after each navigation.

Test traffic shows up / your own visits count. Open the site once with ?x3_notrack=1 on every device you use, or mark visits with ?x3_test=1 (excluded by default).

Numbers differ from Google Analytics. X3 counts sessions without cookies and filters bots strictly; visitors are a per-day estimate. Compare sessions and pageviews, not users.

Still stuck

GET /v1/projects/{project}/status (or the dashboard status line) shows ingest pauses, quotas, dropped events, rescoring progress and the proxy warning. Outside production the API adds an x-3x-debug header to ingest responses with the session and stitch result per pageview.

#Troubleshooting

#Start here

#Status codes of POST /v1/e

#No requests at all