Documentation

Troubleshooting Velotrak

Updated 17 Nov 2026

A click 404s when the campaign or flow is not active, or when the path has no active lander and offer. A postback 403s when the network key does not belong to the click's offer. LP Protect answers everyone else with an empty 403.

Click responses

GET /healthz returns {"status":"ok"} when the process is up. The installer waits on that URL.

What you see Cause in the click handler
503 not ready The in-memory snapshot is not loaded yet.
404 campaign not found The id is unknown, or the campaign is not active. Paused and draft campaigns are omitted from the snapshot.
404 flow not found The flow is missing or not active.
404 no available offer The path’s landers or offers are all paused, or every offer is over its daily cap. There is no fallback path.
404 no target The decision produced nothing to redirect to.
404 unknown click on /go The click id is not in the lookup.

The admin warns before you copy a link when the campaign is inactive, the flow is empty or paused, or the offers or landers are paused.

Postbacks and pixels

Unknown network key: 401. Right key, wrong network for that click: 403 network_mismatch, nothing booked, no CAPI. The inbound log shows rejected. A hosted lander on a hostname you did not register is sandboxed, so its pixel cannot read the tracking cookies. Register the host on the Domains page and make the proxy pass Host through. A proxied hostname that challenges postbacks, or that stores the edge address instead of the visitor, is covered in Cloudflare.

If country, region, and city are empty after install, the GeoIP download may have failed. The installer looks for /var/lib/velotrak/geoip/dbip-city.mmdb and warns when it cannot fetch one.

LP Protect and login

LP Protect without a valid vt_lp token returns an empty 403. The entry token lasts 5 minutes and is tied to IP and user agent. The session after that lasts 2 hours. The feature is Pro. On plain HTTP, a preview of a protected page can fail to load its CSS and JS.

If every admin session died after an upgrade, the master key may have been created for the first time (older builds used an empty key, and those sessions were invalidated). New installs from the script already set a master key. Losing master.key does not stop clicks. It does stop decryption of integration credentials until you enter them again. Keep it with your backups.

More on the happy path: installation, flows, conversions.

Questions

Q1Does tracking stop when the license server is down?
No. Click, postback, and CAPI delivery are outside the license checks. A paid license with no heartbeat for 30 days stays paid. After the subscription period ends, create actions fall back to Free limits for 7 days, then the plan becomes Free.
Q2Why is my postback ignored?
A wrong network key is 401. A key for a different network than the offer the click used is 403 network_mismatch and is not booked. A status the ledger will not move to returns 200 ignored.