Error handling

If you are just getting started with Fingerprint, we recommend reading the following guides first:

If this page does not help you troubleshoot your problem with the JavaScript agent, please contact our support team.

Errors

The JavaScript agent’s load() and get() functions return a promise which will be rejected in case of an error. The table below summarizes the possible types of errors.

Error constant	Short description
`FingerprintJS.ERROR_NETWORK_CONNECTION`	Connecting to the Fingerprint server failed. This is often caused by ad blockers. Logged as `Network connection error`.
`FingerprintJS.ERROR_NETWORK_ABORT`	Fingerprint server request is aborted. Logged as `Network request aborted`.
`FingerprintJS.ERROR_API_KEY_MISSING`	Public API key is missing. Logged as `API key required`.
`FingerprintJS.ERROR_API_KEY_INVALID`	Public API key is invalid. Logged as `API key not found`.
`FingerprintJS.ERROR_API_KEY_EXPIRED`	Public API key is expired. Logged as `API key expired`.
`FingerprintJS.ERROR_BAD_REQUEST_FORMAT`	Bad Fingerprint server request data. Can be caused by a wrong TLS endpoint. Logged as `Request cannot be parsed`.
`FingerprintJS.ERROR_BAD_RESPONSE_FORMAT`	Bad Fingerprint server response data. Can be caused by a wrong endpoint. Logged as `Response cannot be parsed`.
`FingerprintJS.ERROR_GENERAL_SERVER_FAILURE`	General request server-side failure. Logged as `Request failed`.
`FingerprintJS.ERROR_CLIENT_TIMEOUT`	Client-side timeout. Logged as `Client timeout`.
`FingerprintJS.ERROR_SERVER_TIMEOUT`	Server request times out. Logged as `Request failed to process`.
`FingerprintJS.ERROR_RATE_LIMIT`	Request rate limit is exceeded. Logged as `Too many requests, rate limit exceeded`.
`FingerprintJS.ERROR_FORBIDDEN_ORIGIN`	Identification request is blocked due to forbidden origin (see Request filtering). Logged as `Not available for this origin`.
`FingerprintJS.ERROR_FORBIDDEN_HEADER`	Identification request is blocked due to forbidden HTTP header (see Request filtering). Logged as `Not available with restricted header`.
`FingerprintJS.ERROR_NETWORK_RESTRICTED`	Identification request is blocked due to forbidden IP range (see Network request filtering). Logged as `Network restricted`.
`FingerprintJS.ERROR_WRONG_REGION`	The region set in the agent options doesn’t match the region that was used to create your workspace. Logged as `Wrong region`.
`FingerprintJS.ERROR_SUBSCRIPTION_NOT_ACTIVE`	Your workspace hasn’t been activated in the dashboard. Logged as `Subscription not active`.
`FingerprintJS.ERROR_UNSUPPORTED_VERSION`	The JavaScript agent version is not supported. Logged as `Unsupported version`.
`FingerprintJS.ERROR_SCRIPT_LOAD_FAIL`	Failed to load the latest JavaScript agent code. Only available in the NPM installation method. This is often caused by ad blockers. Logged as `Failed to load the JavaScript script of the agent`.
`FingerprintJS.ERROR_INSTALLATION_METHOD_RESTRICTED`	The JavaScript agent installation method is not allowed. Logged as `Installation method restricted`.
`FingerprintJS.ERROR_CSP_BLOCK`	Blocked by the Content Security Policy of the page. Logged as `Blocked by CSP`.
`FingerprintJS.ERROR_INTEGRATION_FAILURE`	Failure on the integration side. Logged as `Integration failed`.
`FingerprintJS.ERROR_INVALID_ENDPOINT`	The given endpoint is not a valid URL. Logged as `The endpoint parameter is not a valid URL`.
`FingerprintJS.ERROR_INVALID_PROXY_INTEGRATION_SECRET`	The integration’s proxy secret is missing, incorrect, or belongs to a different Fingerprint workspace than the public API key in the identification request. See to documentation of your proxy integration for more information. Logged as `Invalid proxy integration secret`.
`FingerprintJS.ERROR_PROXY_INTEGRATION_SECRET_ENVIRONMENT_MISMATCH`	The integration’s proxy secret is scoped to a different environment than the public API key in the identification request. Logged as `Proxy integration secret environment mismatch`.
`FingerprintJS.ERROR_INVALID_PROXY_INTEGRATION_HEADERS`	An unexpected implementation error or network misconfiguration of the proxy integration. Contact support for more information. Logged as `Invalid proxy integration headers`.

With the exception of ERROR_CLIENT_TIMEOUT, ERROR_NETWORK_CONNECTION ERROR_NETWORK_ABORT, ERROR_SCRIPT_LOAD_FAIL and ERROR_CSP_BLOCK, all the errors described above will include the requestId field. The methods can also throw other unexpected errors, they should be treated as agent bugs. Error handling example:

const fpPromise = FingerprintJS.load({ /* ... */ })

try {
  const fp = await fpPromise
  const result = await fp.get()
} catch (error) {
  switch (error.message) {
    case FingerprintJS.ERROR_GENERAL_SERVER_FAILURE:
      console.log('Unknown server error. Request id:', error.requestId)
      break
    case FingerprintJS.ERROR_CLIENT_TIMEOUT:
      console.log('Analysis time limit of 10 seconds is exceeded')
      break
    default:
      console.log('Other error')
  }
}

const fpPromise = FingerprintJS.load({ /* ... */ })

fpPromise
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))
  .catch(error => {
    switch (error.message) {
      case FingerprintJS.ERROR_GENERAL_SERVER_FAILURE:
        console.log('Unknown server error. Request id:', error.requestId)
        break
      case FingerprintJS.ERROR_CLIENT_TIMEOUT:
        console.log('Identification time limit of 10 seconds is exceeded')
        break
      default:
        console.log('Other error')
    }
  })

Ad blockers

Ad blockers can block identification requests or prevent the JavaScript agent from loading at all. This usually results in a net::ERR_BLOCKED_BY_CLIENT error in the console, accompanied by Failed to load the JavaScript script of the agent or Network connection error. We offer a variety of proxy integrations to avoid this issue. See Protecting the JavaScript agent from ad blockers for a list of solutions.

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. Whenever the rate limit is exceeded, the request is throttled and an ERROR_RATE_LIMIT error is thrown.

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 (see options: scriptUrlPattern, endpoint). We don’t recommend implementing your own retry mechanism around the JavaScript agent because it can lead to excessive consumption of paid API calls.

TypeScript errors

The JavaScript agent officially supports TypeScript version 5.1 but may work with newer and older versions of TypeScript. If you face a TypeScript error in the .d.ts file provided by Fingerprint (example 1, example 2), consider one of these solutions:

Update TypeScript in your project (recommended)

Update the TypeScript package in your project to version 5.1 or newer.

npm install typescript@^5.1

yarn add typescript@^5.1

Prevent TypeScript from using the library types

In your TS files, import the minified ESM file directly:

JavaScript

import ... from '@fingerprintjs/fingerprintjs-pro'
import ... from '@fingerprintjs/fingerprintjs-pro/dist/fp.esm.min'

In your .d.ts file (if there is no such file, create one anywhere with any name), add the following line:

TypeScript

declare module '@fingerprintjs/fingerprintjs-pro/dist/fp.esm.min'

JavaScript Agent

Server API

Policy and Upgrades

Webhooks

Device Reputation Network API

Management API

Server SDKs

Errors

Ad blockers

Timeouts

Server timeout

Client timeout

Rate limiting

Retrying after an error

TypeScript errors

Update TypeScript in your project (recommended)

Prevent TypeScript from using the library types

​Errors

​Ad blockers

​Timeouts

​Server timeout

​Client timeout

​Rate limiting

​Retrying after an error

​TypeScript errors

​Update TypeScript in your project (recommended)

​Prevent TypeScript from using the library types

Errors

Ad blockers

Timeouts

Server timeout

Client timeout

Rate limiting

Retrying after an error

TypeScript errors

Update TypeScript in your project (recommended)

Prevent TypeScript from using the library types