Widget Troubleshooting

Document marker: CLAIMFUL_WIDGET_TROUBLESHOOTING_SENTINEL

When the embedded widget cannot show an offer it enters a hidden error state — the checkout is never blocked (fail-open). Because that state is invisible on the page, a misconfigured embed can look "fine" while silently doing nothing.

To make that visible to you, the widget logs one structured diagnostic line to the browser console every time it enters the error state:

[claimful-widget] <code>: <hint> https://claimful.ai/docs/widget-troubleshooting

Open your browser's developer console (F12) on the page with the widget and look for a line beginning with [claimful-widget]. The <code> tells you what went wrong. This line is emitted in production builds — you do not need a debug flag.

Diagnostic codes

configure_invalid

Cause. The widget was configured with no publishable key, or with a configuration key it does not accept.

Fix. Pass your publishable key (wk_…) either as the data-publishable-key attribute on the <claimful-widget> element, or as publishableKey in Claimful.configure({ … }). Order and event data flow through the declarative data-* attributes only — passing them (or other unsupported keys) to configure() also triggers this code.

key_rejected

Cause. The publishable key was rejected by the API (HTTP 401 or 403).

Fix. Confirm the key is a publishable widget key that belongs to this merchant account, that it has not been rotated or revoked, and that it is enabled. Copy it again from your dashboard to rule out a truncated paste.

origin_blocked

Cause. The request never reached an HTTP status. This is most often a blocked origin — your site's domain is not in the key's allowed origins list (a CORS rejection) — but it can also be a general network failure.

Fix. Add your storefront origin (for example https://shop.example.com) to the allowed origins for the key in your dashboard. If the origin is already listed, check that the shopper's network can reach api.claimful.ai.

quote_failed

Cause. The protection API was reached but did not return a usable offer in time — a timeout, or a 5xx server response. The widget auto-retries a few times with backoff before it gives up.

Fix. This is usually transient. If it persists, check the Claimful status page and retry. Nothing on your side needs to change.

Reporting back to us

Alongside the console line, the widget sends a tiny, best-effort telemetry beacon (the diagnostic code and your merchant id — never any customer data or token) so your team can see misconfigured embeds surfaced on the Go-live checklist page in the merchant dashboard as a weekly count. It is fire-once-per-page-load and fail-open: if it cannot send, nothing on the page is affected.