Troubleshooting

Common errors

Session creation errors

Error	Cause	Fix
"Error from verifier: Unauthorized ..."	Invalid or missing API key	Check that your key starts with verify_, has no trailing whitespace, and matches your environment (production vs. staging).
"Error making request: timeout of 5000ms exceeded"	Verify API is unreachable or slow	Check your network connection and verify the API URL. If using a custom verifierUrl, ensure it’s correct.
"Error making request: ..."	General network failure	Check connectivity, firewall rules, and DNS resolution for api.verify.spruceid.com.

Verification UI errors

Error	Cause	Fix
"Element with ID "{divId}" not found"	The container <div> doesn’t exist in the DOM when launchMdlVerification() is called	Ensure the div is rendered before calling. In React, use useEffect; in Svelte, call from an event handler or onMount; in Vue, use nextTick().
"Verification cancelled by user"	The user closed the verification modal	This is not an error. Handle it gracefully — prompt the user to try again if appropriate.
"Verification failed"	Credential verification failed in the iframe	Fetch results from your backend to see specific errors in the errors object.

Results errors

Error	Cause	Fix
"Error from verifier: Not Found ..."	Session expired or already consumed	Sessions expire after 10 minutes and are single-read. Create a new session and try again.
status: 'error' in results	Credential validation failed	Check results.errors for details (signature errors, certificate issues, revocation). results.response may contain partial data.

For detailed error handling patterns and code examples, see Understanding results — Handling errors.

Iframe not appearing

If the iframe doesn’t appear after calling launchMdlVerification():

1. Check the container div exists — Inspect the DOM and confirm the element with your divId is present.
2. Check Content Security Policy — If your site uses a CSP frame-src directive, ensure it allows the Verify iframe domain. The iframe URL is in sessionData.iframe_url.
3. Check the browser console — Look for errors related to frame loading, CSP violations, or permissions policy issues.
4. Verify the session is fresh — Sessions expire after 10 minutes. If you’re reusing stale session data, create a new session.

---

HTTPS requirements

• Production: HTTPS is required for the Digital Credentials API. The QR code flow works on HTTP but HTTPS is still recommended.
• Development: localhost works without HTTPS for both flows.

Iframe permissions

The SDK creates its iframe with allow="digital-credentials-get". If your site explicitly sets a Permissions-Policy header, ensure it includes digital-credentials-get for the iframe origin.