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 or region is not the one associated |
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 and/or regionCode | Contact your Heuristik representative to verify the token and region code |
| 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 |
| Local networks permission warning appears | The 'Apps on Device' permission is not accepted or is not being delegated to the iframe | Check in your browser settings that your website has permission enabled for 'Applications on device' and that this permission is being delegated when loading the iframe using allow="local-network-access" |
| Local networks permission warning appears (II) | The iframe is loading on an http website and the browser blocks the connection due to mixed content | Generate and configure a security certificate to be able to load your website with the https protocol and avoid communication due to mixed content |
| Copy buttons do not work | The 'Clipboard' permission is not accepted or is not being delegated to the iframe | Check in your browser settings that your website has 'Clipboard' permission enabled and that this permission is being delegated when loading the iframe using allow="clipboard-write" |
| 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 |