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.
Error | Short description |
---|---|
FingerprintJS.ERROR_NETWORK_CONNECTION | Fingerprint server connection error. Probably caused by an ad blocker. How to protect from ad blockers. |
FingerprintJS.ERROR_NETWORK_ABORT | Fingerprint server request is aborted |
FingerprintJS.ERROR_API_KEY_MISSING | Public API key is missing |
FingerprintJS.ERROR_API_KEY_INVALID | Public API key is invalid |
FingerprintJS.ERROR_API_KEY_EXPIRED | Public API key is expired |
FingerprintJS.ERROR_BAD_REQUEST_FORMAT | Bad Fingerprint server request data. Can be caused by a wrong TLS endpoint. |
FingerprintJS.ERROR_BAD_RESPONSE_FORMAT | Bad Fingerprint server response data. Can be caused by a wrong endpoint. |
FingerprintJS.ERROR_GENERAL_SERVER_FAILURE | General request server-side failure |
FingerprintJS.ERROR_CLIENT_TIMEOUT | Client-side timeout |
FingerprintJS.ERROR_SERVER_TIMEOUT | Server request times out |
FingerprintJS.ERROR_RATE_LIMIT | Request rate limit is exceeded |
FingerprintJS.ERROR_FORBIDDEN_ORIGIN | Analysis request is blocked due to a forbidden origin (see request filtering) |
FingerprintJS.ERROR_FORBIDDEN_HEADER | Analysis request is blocked due to a forbidden HTTP header (see request filtering) |
FingerprintJS.ERROR_FORBIDDEN_ENDPOINT | Analysis request is blocked due to a forbidden endpoint . Probably because the default endpoint is used instead of the custom subdomain. |
FingerprintJS.ERROR_WRONG_REGION | The region set in the agent options doesn't match the region that was used to create your application |
FingerprintJS.ERROR_SUBSCRIPTION_NOT_ACTIVE | Your application hasn't been activated in the dashboard |
FingerprintJS.ERROR_UNSUPPORTED_VERSION | The JS agent version is not supported |
FingerprintJS.ERROR_SCRIPT_LOAD_FAIL | Failed to load the JS agent code. The error is available only for NPM installation. |
FingerprintJS.ERROR_INSTALLATION_METHOD_RESTRICTED | The JS agent installation method is not allowed |
FingerprintJS.ERROR_CSP_BLOCK | Blocked by the Content Security Policy of the page |
FingerprintJS.ERROR_INTEGRATION_FAILURE | Failure on the integration side |
FingerprintJS.ERROR_INVALID_ENDPOINT | The 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'