Troubleshooting and SDK errors (Web)

This page covers errors you can encounter when integrating our Web SDK. The SDK surfaces failures through callbacks rather than typed error objects, so you handle them inline at the call site.

Tokenization errors

form.tokenize(success, error) accepts two callbacks. The error callback receives an object with a message describing what went wrong. Common causes:

Cause	Description
Validation failure	The user's input failed the component's built-in validation. For example, a confirm-password field whose value doesn't match its paired password field, or an empty required field.
Component not mounted	tokenize() was called before the component finished mounting, or after it was removed from the DOM.
UI keyUI key A public key that authorizes Weavr's Secure UI components — the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. not initialized	OpcUxSecureClient.init() wasn't called before the form was used.
Network error	The browser couldn't reach our tokenization endpoint.

Handle the error callback to show actionable feedback to the user and recover gracefully:

form.tokenize(
  function (tokens) {
    // success path
  },
  function (err) {
    console.error("tokenize failed", err.message);
  }
);

Association errors

OpcUxSecureClient.associate(token, success, error) fails if the user authentication token is invalid, expired, or not stepped-up when the components require step-up.

Cause	Description
Invalid or expired token	The token has been revoked, expired, or doesn't match the UI keyUI key A public key that authorizes Weavr's Secure UI components — the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key.. Sign the user in again to get a fresh token.
Step-up required	The token isn't stepped-up, and the component being mounted requires it.
UI keyUI key A public key that authorizes Weavr's Secure UI components — the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. not initialized	OpcUxSecureClient.init() wasn't called before associate.

window.OpcUxSecureClient.associate(
  "Bearer USER_TOKEN",
  function () {
    // success path — mount user-scoped components here
  },
  function (e) {
    console.error("associate failed", e);
  }
);

KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. and KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. component errors

The KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. and KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. components surface errors through the onError callback (KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers.) or the messageType === "error" branch of the message callback (KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. and director KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers.). The payload describes the failure:

Message type	Description
error	Initialization failed, the user authentication token is invalid, or the reference returned by the corresponding API call is missing or expired.
kybRejected / kycRejected	The verification flow completed but didn't pass. The user needs to retry or your team needs to review the case.

window.OpcUxSecureClient.consumer_kyc().init({
  // ...
  onError: function (message) {
    console.error("KYC error:", message);
  },
});

Common pitfalls and troubleshooting

• OpcUxSecureClient is undefined: the script tag hasn't loaded, or your code runs before the script finishes parsing. Move your initialization into a DOMContentLoaded listener or after the script tag.
• Component renders empty: the mount selector doesn't match an element in the DOM. Verify the element exists when mount() is called.
• Sandbox token in live: the SDK URL and the UI keyUI key A public key that authorizes Weavr's Secure UI components — the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. must come from the same environment. Mixing the sandbox bundle with a live UI keyUI key A public key that authorizes Weavr's Secure UI components — the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key. (or the reverse) fails silently or produces association errors.