Troubleshooting
Validation and error states
When the iframe loads, it validates the token and origin against the Heuristik API:
Error codes
| HTTP Code | Constant | Meaning |
|---|---|---|
401 | UNAUTHORIZED_CODE | Token is invalid |
403 | — | Origin does not match the registered URL |
409 | CONFLICT_CODE | Token is already associated with an active session |
421 | MISDIRECTED_CODE | Request was directed to the wrong server |
424 | FAILED_DEPENDENCY_CODE | A required upstream service is unavailable |
When validation fails, the iframe displays the NotAllowedIframeModal with an error message. No postMessage is sent to the parent.
Common issues
| Symptom | Cause | Resolution |
|---|---|---|
| Iframe shows error modal immediately | Invalid tokenIframe | Contact your Heuristik representative to verify the token |
| Iframe shows error modal on valid token | Origin mismatch — your URL doesn't match the registered URL | Verify with your Heuristik representative that the allowed URL matches your domain exactly |
| Cookie warning appears | Third-party cookies are blocked | Enable cookies for iframe.heuristik.com in browser settings |
| Scanner not detected | Local driver not running | Start the local driver service on the workstation |
| Scanner not detected (driver running) | WebSocket connection blocked | Ensure ws://127.0.0.1:2794 is not blocked by firewall or proxy |
No postMessage received | Origin validation in listener is wrong | Verify you check against https://iframe.heuristik.com |
409 Conflict error | Token already in use by another session | Wait for the active session to end, or contact your Heuristik representative to release the token |