JavaScript error handling

The JavaScript SDK uses ShieldLabsError for validation, loading and identification failures. Branch on code; use message for diagnostics.

import { load, ShieldLabsError } from '@shieldlabs-ai/js';

try {
  const agent = await load({ publicKey: 'PUBLIC_API_KEY' });
  const result = await agent.identify();
  console.log(result.requestId);
} catch (error) {
  if (error instanceof ShieldLabsError) {
    console.error(error.code, error.message);
  } else {
    throw error;
  }
}

Error fields

string

required

Always ShieldLabsError.

ShieldLabsErrorCode

required

One of the five values below.

string

required

A human-readable explanation. Do not use its wording as an application contract.

unknown

The underlying error when available, such as a failed module import.

Error codes

Code	Cause	Action
`invalid_options`	Invalid key, user ID, timeout, URL or interaction target	Correct the input before retrying
`unsupported_environment`	Server rendering, worker or insecure browser context	Run on a browser page over HTTPS or localhost
`load_failed`	CDN import failed or the module lacks required methods	Check connectivity and CSP; retry loading with a bound
`not_initialized`	Agent did not return an initialized Identification ID	Keep the action pending or use your failure path
`timeout`	Loading or initialization exceeded the configured wait	Check connectivity and timeout settings; avoid unbounded retries

load(), identify() and check() report failures through rejected promises. identifyOnInteraction() validates arguments synchronously. Its take() method returns a promise. check() converts not_initialized into null. This includes cooldown skips; null is not a risk result.

Separate browser errors from API errors

A browser timeout does not identify an HTTP status or prove that no check was accepted. Server API failures have their own HTTP status codes. Verify the server result before completing a protected action.

Run a check

Get the result

Account

Contracts

JavaScript error handling

Error fields

Error codes

Separate browser errors from API errors

​Error fields

​Error codes

​Separate browser errors from API errors

Error fields

Error codes

Separate browser errors from API errors