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:

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.

ErrorShort description
FingerprintJS.ERROR_NETWORK_CONNECTIONFingerprint server connection error. Probably caused by an ad blocker. How to protect from ad blockers.
FingerprintJS.ERROR_NETWORK_ABORTFingerprint server request is aborted
FingerprintJS.ERROR_API_KEY_MISSINGPublic API key is missing
FingerprintJS.ERROR_API_KEY_INVALIDPublic API key is invalid
FingerprintJS.ERROR_API_KEY_EXPIREDPublic API key is expired
FingerprintJS.ERROR_BAD_REQUEST_FORMATBad Fingerprint server request data. Can be caused by a wrong TLS endpoint.
FingerprintJS.ERROR_BAD_RESPONSE_FORMATBad Fingerprint server response data. Can be caused by a wrong endpoint.
FingerprintJS.ERROR_GENERAL_SERVER_FAILUREGeneral request server-side failure
FingerprintJS.ERROR_CLIENT_TIMEOUTClient-side timeout
FingerprintJS.ERROR_SERVER_TIMEOUTServer request times out
FingerprintJS.ERROR_RATE_LIMITRequest rate limit is exceeded
FingerprintJS.ERROR_FORBIDDEN_ORIGINAnalysis request is blocked due to a forbidden origin (see request filtering)
FingerprintJS.ERROR_FORBIDDEN_HEADERAnalysis request is blocked due to a forbidden HTTP header (see request filtering)
FingerprintJS.ERROR_FORBIDDEN_ENDPOINTAnalysis request is blocked due to a forbidden endpoint. Probably because the default endpoint is used instead of the custom subdomain.
FingerprintJS.ERROR_WRONG_REGIONThe region set in the agent options doesn't match the region that was used to create your application
FingerprintJS.ERROR_SUBSCRIPTION_NOT_ACTIVEYour application hasn't been activated in the dashboard
FingerprintJS.ERROR_UNSUPPORTED_VERSIONThe JS agent version is not supported
FingerprintJS.ERROR_SCRIPT_LOAD_FAILFailed to load the JS agent code. The error is available only for NPM installation.
FingerprintJS.​ERROR_INSTALLATION_METHOD_RESTRICTEDThe JS agent installation method is not allowed
FingerprintJS.ERROR_CSP_BLOCKBlocked by the Content Security Policy of the page
FingerprintJS.ERROR_INTEGRATION_FAILUREFailure on the integration side
FingerprintJS.ERROR_INVALID_ENDPOINTThe given endpoint is not a valid URL

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 prevent the JS agent from loading at all. This usually results in a net::ERR_BLOCKED_BY_CLIENT error in the console. 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 application 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'