Error events

When something goes wrong, embedded components surface the error in two places:

• Inside the iframe as a visible message to the end user, so they don't have to context-switch to figure out what happened.
• Via postMessage to your shell (iframe mode only), so your application can react — re-mint a session, navigate the user away, show a fallback, etc.

In direct-link mode there is no parent to message; the user-facing message is the only signal.

Event shape

Every error event has the same envelope:

{
  "type": "kaunt-error",
  "code": "session-revoked",
  "sessionId": "fb0ccbbc-62bc-447f-a47e-02b490e25690"
}

type is always kaunt-error. code is a machine-readable identifier (table below). sessionId is the session the error relates to, or null if the failure happened before a session was known.

Listen for these alongside the kaunt-ready handshake:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://components.kaunt.com') return;
  if (event.data?.type !== 'kaunt-error') return;

  switch (event.data.code) {
    case 'session-revoked':
    case 'session-unavailable':
      // The session is gone. Don't retry the same URL; mint a fresh one.
      mountFreshSession();
      break;
    case 'handshake-timeout':
      // The iframe never received the token. Usually a postMessage misconfiguration.
      break;
    default:
      console.warn('Kaunt component error:', event.data);
  }
});

Once an error has been reported, no further events are emitted for the same failure — the SPA does not retry, and the parent will not be spammed if the user clicks "retry" in the iframe.

Codes

Code	Meaning	When you should react
session-unavailable	The session ID does not exist, has already been consumed, or has expired before being loaded.	Mint a new session and reload the iframe. Do not retry the same URL.
session-revoked	A valid session was invalidated mid-flight, either explicitly via DELETE or because the underlying user/account was disabled.	Treat as a sign-out signal. Stop displaying the component until a new session is available.
handshake-timeout	Iframe mode: the SPA sent kaunt-ready but did not receive a kaunt-token within 5 seconds.	Almost always a wiring issue on the parent side: missing event listener, wrong target origin, JWT for a different session.
no-referrer	Iframe mode: the SPA could not determine its parent's origin from document.referrer.	The page hosting the iframe is using a referrer policy that strips the referrer entirely (no-referrer). Switch to a policy that exposes at least the origin.
missing-session	The SPA was loaded without a sessionId query parameter.	Almost always a developer typo or a stale link.
invalid-mode	The SPA was loaded with no mode, or with a mode other than iframe/direct-link.	Same as above.
token-fetch-failed	Direct-link mode: the SPA could not reach Kaunt to exchange the session ID for a JWT.	Transient network issue. Retrying the link (if not yet consumed) is safe.
malformed-response	The token-exchange response was structurally invalid.	Should never happen in production. Report to Kaunt support with the correlation ID from your network tab.

If new codes are added in future, they will appear here; treat unknown codes as transient and surface them in logs.

What does not generate an error event

• Validation failures from the user's own actions (e.g. submitting empty feedback) are shown inline in the component and don't post a kaunt-error. They're part of normal UX, not a signal your shell needs to handle.
• 4xx responses to in-component API calls that the SPA can recover from (e.g. transient 409s) are retried silently.
• Manually closing the iframe does not emit an event. There is no kaunt-close message; the parent owns the iframe's lifecycle.