Troubleshooting
Issues integrators are most likely to hit, based on the failure modes the SDK and API are actually built to produce.
GET /v1/public/config/:publicSiteKey returns 404
The site hasn't published a configuration yet. A brand-new site starts as a draft; the public endpoint only ever serves a published version. Call POST /v1/sites/:siteId/publish (session) or POST /v1/agent/sites/:siteId/publish (a token with sites:publish) first, then retry.
The banner never appears
Check, in order:
- Is the site actually published (see above)?
- Is
data-site-key(orsiteKeyincreateNastarClient) the site's public key, not an internal site ID or a setup token? - Did the config fetch fail? The SDK fails closed and silent on fetch errors — check the browser Network tab for the actual response to
/v1/public/config/:publicSiteKeyrather than assuming a bug in your gating code. - Is there already stored consent from a previous config version in
localStorage, and does it happen to match the current version? The banner only re-appears on a version mismatch or missing/malformed storage — clear the site'slocalStoragekey to force it during testing.
An optional script still runs before consent
Almost always means the script tag/loader lives outside the loadWhenConsented callback — e.g. a tag manager that itself unconditionally injects the vendor script regardless of a dataLayer signal. Verify by watching the Network tab before making any choice: nothing beyond the config fetch and the SDK's own bundle should appear.
CORS error calling the API from the browser
/v1/public/* allows any origin. Every other route (/v1/auth, /v1/organizations, /v1/sites, /v1/agent) only allows the configured dashboard origin for cookie-credentialed requests — a setup-token-authenticated call to /v1/agent from a browser page on a different origin will be blocked by CORS even though the Bearer token itself is valid. Call /v1/agent/* from a server/CLI context, not directly from a customer site's frontend.
401 from /v1/agent/*
The token is missing, malformed, revoked, or expired (default 30-day expiry). Check GET /v1/agent/me first when debugging — it needs no scope beyond a valid token, and its response confirms exactly what organization/site/scopes the token actually carries.
403 from /v1/agent/sites/:siteId/...
Either the token doesn't have the scope the route requires (sites:write for banner-copy, sites:publish for publish), or the token is bound to a different site than the one in the URL. Create a new token with the right scope/site binding rather than trying to reuse one that was scoped for something else.
The one-time code email never arrives
Check spam/junk first — transactional mail from a new sender sometimes lands there. Requesting another code is rate-limited (one per 60 seconds, up to 5 per hour for the same address); a rapid double-click on "send code" can look like a missing email when it's actually a rejected duplicate request. If it still doesn't arrive after a minute, request a fresh code rather than reusing an old one — codes expire after 10 minutes.
Consent decision doesn't survive a reload
Confirm the site is genuinely still on the same published config version — a republish bumps the version and intentionally discards stale stored consent (see SDK reference). If the version hasn't changed, check whether the page is in a context where localStorage is blocked (private browsing with storage disabled, a third-party-cookie-blocking iframe) — the SDK degrades to "first visit every load" there by design, not as a bug.
Still stuck
There's no public support channel yet — that one genuinely isn't built. Check API reference and the interactive /v1/docs UI for the exact request/ response shape, since most integration issues turn out to be a field name or auth-model mismatch rather than a product bug.