Error handling

This page contains a reference for errors, timeouts, and other potential problems you can encounter while using the JavaScript agent.

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

• Install the JavaScript agent
• Identify visitors

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.

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 JS 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 JS agent option (see options: scriptUrlPattern, endpoint).

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

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

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