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.

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.

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

See our CSP documentation to correctly configure the exceptions needed for our JavaScript agent and WebWorker.

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 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 JS agent option.

We don’t recommend implementing your own retry mechanism around the JS 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.

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 JS 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 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