Skip to main content

​
Error Handling

createToken() and createBankToken() both throw an OzError when tokenization fails. Wrap calls in a try/catch and inspect .errorCode to decide how to respond.

​
OzError

import { OzError } from '@ozura/elements';

try {
  const { token } = await vault.createToken();
} catch (err) {
  if (err instanceof OzError) {
    console.error(err.message);    // user-facing message
    console.error(err.errorCode);  // machine-readable code
    console.error(err.raw);        // raw message from vault (for logging)
    console.error(err.retryable);  // boolean: safe to retry?
  }
}

​
OzError properties

PropertyTypeDescription
messagestringNormalized, user-friendly error message
errorCodeOzErrorCodeMachine-readable code (see table below)
rawstringRaw message returned by the Vault API (use for logging, not display)
retryablebooleantrue for transient errors (network, timeout, server). false for permanent failures where retrying with the same input won’t help.

​
Error Codes

errorCoderetryableMeaningWhat to do
'network'✅Request failed due to a network error (offline, DNS failure, etc.)Show a “check your connection” message. Retry is safe.
'timeout'✅Tokenization took longer than 30 secondsShow a timeout message. Retry is safe.
'server'✅Vault returned a 5xx errorRetry after a short delay. Log for investigation.
'auth'❌Invalid or missing API key / pub keyCheck your credentials. Do not retry without fixing config.
'validation'❌Request was malformed or the vault rejected inputCheck request parameters. Usually a developer error.
'config'❌SDK misconfiguration (e.g. disallowed vault origin)Check your apiUrl configuration.
'unknown'❌Unclassified errorLog and surface a generic message.
import { OzVault, OzError } from '@ozura/elements';

async function handlePay() {
  try {
    const { token, cvcSession } = await vault.createToken({
      billing: { firstName: 'Jane', lastName: 'Smith' },
    });

    await submitPayment(token, cvcSession);

  } catch (err) {
    if (!(err instanceof OzError)) throw err; // rethrow unexpected errors

    if (err.retryable) {
      showError('Connection issue — please try again.');
    } else {
      switch (err.errorCode) {
        case 'auth':
          showError('Configuration error. Please contact support.');
          console.error('[OzElements] Auth error:', err.raw);
          break;

        case 'validation':
          showError('Payment details could not be verified. Please check your card.');
          break;

        case 'config':
          showError('Configuration error. Please contact support.');
          console.error('[OzElements] Config error:', err.raw);
          break;

        default:
          showError('Something went wrong. Please try again.');
          console.error('[OzElements] Unexpected error:', err);
      }
    }
  }
}

​
SDK-Level Errors (Thrown Before Tokenization)

Some errors are thrown by the SDK before any network request is made. These are also OzError instances:
ConditionMessage
Vault not yet ready"Vault not ready. Ensure the page is fully loaded before calling createToken."
Tokenization already in progress"A tokenization is already in progress. Wait for it to complete before calling createToken() again."
No elements mounted"No elements are mounted and ready. Mount at least one element before calling createToken."
Vault destroyed"Cannot tokenize on a destroyed vault. Create a new OzVault instance."
Missing firstName (bank)"firstName is required for bank account tokenization."
Missing lastName (bank)"lastName is required for bank account tokenization."
These are typically developer errors caught during integration.

​
Load Errors

If the tokenizer iframe fails to load (network issue, blocked by CSP, etc.), use onLoadError: 
const vault = new OzVault('YOUR_API_KEY', {
  pubKey: 'YOUR_PUB_KEY',
  onLoadError: () => {
    showError('Payment fields could not load. Please refresh and try again.');
  },
  loadTimeoutMs: 8000, // default: 10000
});
Individual element load failures emit a loaderror event: 
cardNumber.on('loaderror', () => {
  showError('Card number field failed to load. Please refresh.');
});

​
normalizeCardSaleError

If you’re using PayAPI to process a charge and need to map raw error strings to user-friendly messages, normalizeCardSaleError handles this: 
import { normalizeCardSaleError } from '@ozura/elements';

try {
  await chargeCard(token);
} catch (err) {
  const message = normalizeCardSaleError(err.message);
  showError(message);
}

​
Next Steps

API Reference

Full OzError type definition and all SDK types.

Card Elements

createToken() full reference.