> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript error handling

> Handle ShieldLabsError codes from loading and identifying in the browser.

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

```ts theme={null}
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

**name** `string` *required*

Always `ShieldLabsError`.

**code** `ShieldLabsErrorCode` *required*

One of the five values below.

**message** `string` *required*

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

**cause** `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](https://docs.shieldlabs.ai/setup/csp.md); 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](https://docs.shieldlabs.ai/api/server-api.md#errors). Verify the server result before completing a protected action.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.