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

# Error handling

> Error handling overview and best practices for JavaScript agent

JavaScript agent exposes errors in a predictable and actionable way. This guide explains how it surfaces errors, how you can identify them, and how you should handle them in your application.

## Overview

Both the `start()` and `get()` methods can throw errors, we recommend wrapping them in a `try/catch` block to prevent any unwanted errors popping up in the browser developer console.

All JavaScript agent errors are represented by the `FingerprintError` class. These errors include both a human-readable message and an error `code`.

```ts theme={"theme":"github-dark-dimmed"}
class FingerprintError extends Error {
  name: "FingerprintError"
  code: string
  event_id: string | null
}
```

We use error codes to ensure your application logic does not depend on error message text, which may change over time.

## Handling Errors

We provide the `isFingerprintError()` helper so you can reliably distinguish JavaScript agent errors from generic JavaScript errors.

```jsx theme={"theme":"github-dark-dimmed"}
import * as Fingerprint from "@fingerprint/agent"

try {
  const fp = Fingerprint.start({ apiKey })
} catch (error) {
  if (Fingerprint.isFingerprintError(error)) {
    console.error(error.code, error.message)
  }
}
```

You should always use this helper instead of checking error names or messages directly.

***

## Error Codes

### Configuration Errors

Configuration errors occur during initialization when required options are missing or invalid.
These errors are **not retryable** and must be fixed in your configuration.

| Code                      | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `api_key_missing`         | You did not provide the `apiKey` option        |
| `api_key_invalid`         | The `apiKey` option is not a string            |
| `endpoints_misconfigured` | The `endpoints` option is invalid              |
| `invalid_endpoint`        | An endpoint is not a valid URL                 |
| `cache_misconfigured`     | The `cache` option is misconfigured            |
| `wrong_worker_option`     | The `worker` option is not a `Worker` instance |

***

### Script and Environment Errors

These errors occur when we are unable to load or execute the agent script in the current environment.

| Code               | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `script_load_fail` | Failed to load the agent script                        |
| `csp_block`        | Script blocked by Content Security Policy (CSP)        |
| `sandboxed_iframe` | Running in an unsupported sandboxed iframe environment |

<Info>
  See our [CSP documentation](/docs/js-agent-csp) to correctly configure the exceptions needed for our JavaScript agent and WebWorker.
</Info>

### Network and Runtime Errors

These errors may occur during initialization or data collection and are often temporary.

| Code                  | Description                             |
| --------------------- | --------------------------------------- |
| `client_timeout`      | The operation timed out                 |
| `network_connection`  | A network request failed                |
| `network_abort`       | A request was aborted                   |
| `bad_response_format` | We could not parse the backend response |

We automatically retry these errors where appropriate.

## Timeouts

Two types of timeouts are possible: a server timeout and a client timeout.
​

### Server timeout

The server timeout is fixed at 10 seconds of server-side processing time. If server-side processing exceeds 10 seconds for any reason, the promise will be rejected.
​

### Client timeout

Client timeout controls the total time (both client-side and server-side) that any analysis event is allowed to run. By default, it’s 10 seconds. Note that even if the client-side timeout is exceeded, the server-side request can still be running, and its results will be sent to you via a webhook if enabled.

## Rate limiting

Every workspace API key has a rate limit. It means you cannot make more requests per second than your rate limit allows. See [Account limits](/docs/billing#account-limits) for more details.
​

## Retrying after an error

The JavaScript agent retries automatically in case of failure. If you want the agent to make more attempts, increase the timeout. If you want to retry with another endpoint, set an array of `endpoints` in the JavaScript agent option.

We don’t recommend implementing your own retry mechanism around the JavaScript agent because it can lead to excessive consumption of paid API calls.

## Handling Errors from `start()`

The `start()` method may fail due to configuration issues, script loading failures, or environment restrictions.

```js theme={"theme":"github-dark-dimmed"}
import * as Fingerprint from "@fingerprint/agent"

try {
  const fp = Fingerprint.start({ apiKey })
} catch (error) {
  if (Fingerprint.isFingerprintError(error)) {
    switch (error.code) {
      case "csp_block":
        // Update your CSP to allow the agent script
        break
      case "api_key_missing":
        // Fix your configuration
        break
      default:
        // Log the error and fail gracefully
    }
  }
}
```

## Ad blockers

Ad blockers can interfere with identification requests or prevent the JavaScript agent from loading. This typically results in a `net::ERR_BLOCKED_BY_CLIENT` error in the browser console, along with messages such as "Failed to load the JavaScript script of the agent" or "Network connection error".

To avoid these issues, we provide several proxy integration solutions. Refer to [Protecting the JavaScript agent from ad blockers](/docs/protecting-the-javascript-agent-from-adblockers) for detailed guidance on available options.
​

## Best Practices

We recommend that you:

* Always wrap `start()` and `get()` in a `try/catch` block
* Use `isFingerprintError()` to detect and handle JavaScript agent errors
* Treat configuration errors as non-retryable